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Introduction 


Most of the routines, functions, and structures described in this manual are part 
of both the DDI and the DKI (cross-referenced by DxDK). As Figure 1 shows, 
drivers written to conform to both interfaces are portable to all computers sup¬ 
porting UNIX System V Release 4 Multi-Processor for Intel Processors, and they 
will be compatible through and beyond Release 4 Multi-Processor. 


NOTE 


Note that drivers written to conform with this version of the DDI/DKI may not 
run on systems running UNIX System V Release 4 or Release 4.1 Enhanced 
Security, as those releases do not implement the new multiprocessor inter¬ 
faces. 


However, a driver written to conform to both interfaces is not guaranteed to be 
binary compatible with future releases of the operating system. Binary compati¬ 
bility requires more than just interface definition. It also requires that values for 
#def ine's be standardized, for example. The DDI/DKI is a source code inter¬ 
face. Following it is a necessary, but not sufficient, condition for binary compa¬ 
tibility. To understand more completely what is meant by "portable" and 
"compatible" for the DDI and DKI, the scope of each interface must be more 
thoroughly explained. 


Porting 

Software is usually considered portable if it can be adapted to run in a different 
environment at a lower cost than if one were to rewrite it. The new environ¬ 
ment may include a different processor, operating system, and even the 
language in which the program is written, if a language translator is available. 
More often, however, software is ported between environments that share an 
operating system, processor, and source language. The source code is modified 
to accommodate the differences in compilers, processors, or releases of the 
operating system. 

In the past, device drivers did not port easily for one or more of the following 
reasons: 

■ To enhance functionality, members had been added to kernel data struc¬ 
tures accessed by drivers, or the sizes of existing members had been 
redefined. 
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■ Driver-Hardware. Most hardware drivers include an interrupt handling 
entry point, and may also perform direct memory access (DMA). These 
and other hardware-specific interactions make up the driver/hardware 
interface. 

■ Driver-Boot/Configuration Software. At boot time, the existence of a 
driver is made known to the system through information in system files, 
enabling the system to include the driver. The interaction between the 
driver and the boot and configuration software is the third interface affect¬ 
ing drivers. Refer to the sections on Installable Drivers (ID) in Chapter 3 
of the Integrated Software Development Guide for more information on this. 


Scope of the Device Driver Interface (DDI) 

The primary goal of DDI is to facilitate both source and binary portability across 
successive releases of UNIX System V on a particular machine. Implicit in this 
goal is an important fact. Although there is only one DKI, each processor pro¬ 
duct has its own DDI. Therefore, if a driver is ever to be ported to different 
hardware, special attention must be paid to the machine-specific routines that 
make up the "DDI only" part of a driver. These include, but are not confined 
to, the driver/hardware interface (as described in the previous section). Some 
processor-specific functionality also may belong to the driver/kernel interface, 
and may not be easy to locate. 

To achieve the goal of source and binary compatibility, the functions, routines, 
and structures specified in the DDI must be used according to these rules. 

■ Drivers cannot access system state structures (for example, u and 
sysinfo) directly. 

■ For structures external to the driver that may be accessed directly, only 
the utility functions provided in Section 3 of this manual should be used. 
More generally, these functions should be used wherever possible. 

■ The header file ddi .h must be included at the end of the list of system 
header files. This header file "undefines" several macros that are reimple¬ 
mented as functions. Device driver-specific include files should be listed 
after ddi.h to insure only the DDI/DKI interface is used by the driver. 
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■ Single-threaded drivers which conform to the DDI/DKI will be portable 
across uniprocessor implementations which support the DDI/DKI. 

■ Multiprocessor implementations which support the DDI/DKI are not 
required to support single-threaded drivers that conform to the DDI/DKI, 
although some multiprocessor implementations may choose to support 
such drivers by preventing concurrent execution of code within a given 
single-threaded driver. 

Driver writers are encouraged to write multithreaded rather than single- 
threaded drivers, as these will be more widely portable and can benefit from the 
parallelism inherent on a multiprocessor. Writing a multithreaded driver 
requires that shared data within the driver be protected against certain forms of 
concurrent access. This is done by using appropriate locking primitives to 
prevent concurrent execution of code which accesses a given piece of shared 
data. This document defines interfaces to several types of locking and syn¬ 
chronization primitives, namely basic locks, read/write locks, sleep locks and 
synchronization variables. Basic locks and read/write locks are intended for use 
within multithreaded drivers, while sleep locks and synchronization variables 
are useful in both single-threaded and multithreaded drivers. The characteris¬ 
tics of the various locking and synchronization primitives are described on the 
relevant manual pages in Section 3. 


Audience 

This manual is for experienced C programmers responsible for creating, modify¬ 
ing, or maintaining drivers that run on UNIX System V Release 4 Multi- 
Processor for Intel Processors and beyond. It assumes that the reader is familiar 
with UNIX system internals and the advanced capabilities of the C Programming 
Language. In addition, programmers writing multithreaded drivers are 
assumed to be familiar with the fundamentals of concurrent programming and 
the appropriate use of locking primitives to protect shared data. 
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The manual contains five sections: 

D1 driver data definitions 

D2 driver entry points 

D3 kernel functions used by drivers 

D4 kernel data structures accessed by drivers 

D5 kernel #def ine's used by drivers 

Each section number is suffixed with a letter indicating the interfaces covered. 
The suffixes used are: 

D Device Driver Interface only (DDI) 

K Driver-Kernel Interface only (DKI) 

DK both DDI and DKI 

X DDI-only Platform-specific Interface 

For example, open(D2DK) refers to the open entry point routine for a driver, not 
to the open(2) system call documented in the Programmer's Reference Manual, 

For clarity, the platform-specific manual pages have been put in an appendix, 
separate from the rest of the DDI/DKI manual pages. 

Reference pages contain the following headings, where applicable: 

■ NAME gives the routine's name and a short summary of its purpose. 

■ SYNOPSIS summarizes the routine's calling and return S 3 mtax. 

■ ARGUMENTS describes each of the routine's arguments. 

■ DESCRIPTION provides general information about the routine. 

■ STRUCTURE MEMBERS describes all accessible data structure members. 

■ RETURN VALUE summarizes the return value from the function. 

■ LEVEL gives an indication of when the routine can be used. 

■ NOTES provides restrictions on use and cautionary information. 

■ SEE ALSO gives sources for further information. 

■ EXAMPLE provides an example of common usage. 
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STREAMS 

The Programmer's Guide: STREAMS tells how to write drivers and access devices 
that use the STREAMS driver interface for character access. 

The Programmer's Guide: Networking Interfaces provides detailed information, 
with examples, on the Section 3N library that comprises the UNIX system Tran¬ 
sport Level Interface (TLI). 

The Programmer's Guide: ANSI C and Programming Support Tools includes instruc¬ 
tions on using a number of UNIX utilities, including make and SCCS. 

Operating Systems 

The UNIX System V reference manuals are the standard reference materials for 
the UNIX operating system. This information is organized into three manuals, 
published separately for each system: 

■ The User's Reference Manual/System Administrator's Reference Manual 
includes information on UNIX system user-level commands (Section 1) and 
administrative commands (Section IM). 

■ The Programmer's Reference Manual: Operating System API includes infor¬ 
mation on UNIX system calls (Section 2) and C language library routines 
(Section 3). 

■ The System Files and Devices Reference Manual includes information on 
UNIX system file formats (Section 4), miscellaneous facilities (Section 5), 
and special device files (Section 7). 
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copies user data from the message 


copies user data from the message 


copy a character to space described . 

copy a message block . 

copy a message . 

copy data between address locations 
copy data from a driver buffer to a . 

copy data from a user buffer to a . 

copy data using uio(D4DK) structure 
copy request structure . 


. dma_get_cb(D3X) 

. dma_cb(D4X) 

dma_get_best_mode(D3X) 

. biowait(D3DK) 

. msgpullup(D3DK) 

. linkb(D3DK) 

. print(D2DK) 

.... mps_mk_bgrant(D3DK) 
.... mps_mk_breject(D3DK) 

. mps_mk_brdcst(D3DK) 

... mps_mk_solrply(D3DK) 

. mps_mk_sol(D3DK) 

mps_mk_unsolrply(D3DK) 

. mps_mk_unsol(D3DK) 

. clrbuf(D3DK) 

. ioctl(D2DK) 

. bcanputnext(D3DK) 

. canputnext(D3DK) 

. bcanput(D3DK) 

. pcmsg(D3DK) 

. putctl(D3DK) 

. putnextctl(D3DK) 

. putnextctl(D3DK) 

. putctl(D3DK) 

. drv_hztousec(D3DK) 

. etoimajor(D3DK) 

. itoemajor(D3DK) 

. drv_usectohz(D3DK) 

. pptophys(D3DK) 

. btop(D3DK) 

. btopr(D3DK) 

. ptob(D3DK) 

. vtop(D3DK) 

.... mps_get_soldata(D3DK) 

mps_get_unsoldata(D3DK) 

. ureadc(D3DK) 

. copyb(D3DK) 

. copymsg(D3DK) 

. bcopy(D3DK) 

. copyout(D3DK) 

.. copyin(D3DK) 

. uiomove(D3DK) 

. copyreq(D4DK) 
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Permuted Index 


intro introduction to kernel 
specified number of clock ticks 
specified number of clock/ delay 
ureadc copy a character to space 
/return a character from space 
a previously allocated DMA buffer 
dma get buf allocate a DMA buffer 
dma buf DMA buffer 
frees a list of data buffer 
a pointer to a list of data buffer 

for certain board types in the 
DMA command dma_get_best_mode 

privileged drv_priv 

start initialize a 
close relinquish access to a 
init initialize a 
intr process a 
ioctl control a character 
virtual mapping for memory-mapped 
convert external to internal major 
numbers makedevice make 

getemajor get external major 
geteminor get external minor 
getmajor get internal major 
getminor get internal minor 
convert internal to external major 
open gain access to a 
read read data from a 
size return size of logical block 
write write data to a 
send a message in the opposite 
qprocsoff 

requests on a DMA/ dma disable 
system console print 
the system cmn err 
free a previously allocated 
dma_get_buf allocate a 
dmabuf 
of hardware requests on a 
of hardware requests on a 
free a previously allocated 
dma_get_cb allocate a 
dma cb 


#define's . intro(D5DK) 

delay delay process execution for a . delay(D3DK) 

delay process execution for a . delay(D3DK) 

described by uio(D4DK) structure . ureadc(D3DK) 

described by uio(D4DK) structure . uwritec(D3DK) 

descriptor dma free buf free . dma_free_buf(D3X) 

descriptor . dma_get_buf(D3X) 

descriptor structure . dma_buf(D4X) 

descriptors mps free dmabuf . mps_free_dmabuf(D3DK) 

descriptors mps get dmabuf returns 

. mps_get_dmabuf(D3DK) 

designated slot /checks . ics agent_cmp(D3DK) 

determine best transfer mode for 


dma_get_best_mode(D3X) 


determine whether credentials are . drv_priv(D3DK) 

devflag driver flags . devflag(DlD) 

device at system start-up . start(D2DK) 

device . close(D2DK) 

device . init(D2DK) 

device interrupt . intr(D2DK) 

device . ioctl(D2DK) 

device mmap check . mmap(D2DK) 

device number etoimajor . etoimajor(D3DK) 

device number from major and minor 

. makedevice(D3DK) 

device number . getemajor(D3DK) 

device number . geteminor(D3DK) 

device number . getmajor(D3DK) 

device number . getminor(D3DK) 

device number itoemajor . itoemajor(D3DK) 

device . open(D2DK) 

device . read(D2DK) 

device . size(D2DK) 

device . write(D2DK) 

direction in a stream qreply . qreply(D3DK) 

disable put and service routines . qprocsoff(D3DK) 

disable recognition of hardware . dma_disable(D3X) 

display a driver message on the . print(D2DK) 

display an error message or panic . cnm_err(D3DK) 

DMA buffer descriptor dma free buf . dma_free_buf(D3X) 

DMA buffer descriptor . dma_get_buf(D3X) 

DMA buffer descriptor structure . dma_buf(D4X) 

DMA channel /disable recognition . dma_disable(D3X) 

DMA channel /enable recognition . dma_enable(D3X) 

DMA command block dma free cb . dma_free_cb(D3X) 

DMA command block . dma_get_cb(D3X) 

DMA command block structure . dma_cb(D4X) 
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dupb duplicate a message block . dupb(D3DK) 

dupb duplicate a message block . dupb(D3DK) 

dupmsg duplicate a message . dupmsg(D3DK) 

dupmsg duplicate a message . dupmsg(D3DK) 

geteblk get an empty buffer . geteblk(D3DK) 

ngeteblk get an empty buffer of the specified size . ngeteblk(D3DK) 

qprocson enable put and service routines . qprocson(D3DK) 

requests on a DMA/ dma enable enable recognition of hardware . dma_enable(D3X) 

serviced enableok allow a queue to be . enableok(D3DK) 

/for transmission and sets up table entries for reception of reply/ 

. mps_AMPsend_rsvp(D3DK) 

character driver chpoll poll entry point for a non-STREAMS . chpoll(D2DK) 

intro introduction to driver entry point routines . intro(D2DK) 

clrbuf erase the contents of a buffer . clrbuf(D3DK) 

ermos error numbers . errnos(D5DK) 

bioerror manipulate error field within a buffer header . bioerror(D3DK) 

cmn err display an error message or panic the system . cmn_err(D3DK) 

geterror retrieve error number from a buffer header . geterror(D3DK) 

errnos error numbers . errnos(D5DK) 

using an externally-supplied/ esballoc allocate a message block . esballoc(D3DK) 

externally-supplied buffer can be/ esbbcall call a function when an . esbbcall(D3DK) 

internal major device number etoimajor convert external to . etoimajor(D3DK) 

inform polling processes that an event has occurred pollwakeup . pollwakeup(D3DK) 

specified length of time itimeout execute a function after a . itimeout(D3DK) 

processor, after a/ dtimeout execute a function on a specified . dtimeout(D3DK) 

clock ticks delay delay process execution for a specified number of . delay(D3DK) 

getemajor get external major device number . getemajor(D3DK) 

itoemajor convert internal to external major device number . itoemajor(D3DK) 

geteminor get external minor device number . geteminor(D3DK) 

number etoimajor convert external to internal major device . etoimajor(D3DK) 

esbbcall call a function when an externally-supplied buffer can be/ . esbbcall(D3DK) 

/allocate a message block using an externally-supplied buffer . esballoc(D3DK) 

ics hostid returns the host id field of the HOST ID record in this/ . ics_hostid(D3DK) 

bioerror manipulate error field within a buffer header . bioerror(D3DK) 

queue qsize find the number of messages on a . qsize(D3DK) 

devflag driver flags . devflag(DlD) 

priority band bcanputnext test for flow control in a specified . bcanputnext(D3DK) 

canputnext test for flow control in a stream . canputnext(D3DK) 

band bcanput test for flow control in specified priority . bcanput(D3DK) 

priority band flushband flush messages in a specified . flushband(D3DK) 

flushq flush messages on a queue . flushq(D3DK) 

specified priority band flushband flush messages in a . flushband(D3DK) 

flushq flush messages on a queue . flushq(D3DK) 

/receives solicited data in fragments when buffer space is not/ 

. mps_AMPreceive_frag(D3DK) 

freeb free a message block . freeb(D3DK) 

freemsg free a message . freemsg(D3DK) 
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error field within a buffer header bioerror manipulate . bioerror(D3DK) 

freerbuf free a raw buffer header . freerbuf(D3DK) 

retrieve error number from a buffer header geterror . geterror(D3DK) 

getrbuf get a raw buffer header . getrbuf(D3DK) 

query whether a sleep lock is held by the caller SLEEP LOCKOWNED 

. SLEEP_LOCKOWNED(D3DK) 

in this/ ics hostid returns the host id field of the HOST ID record . ics_hostid(D3DK) 

/returns the host id field of the HOST ID record in this board's/ . ics_hostid(D3DK) 

board types in the designated slot ics agent cmp checks for certain . ics_agent_cmp(D3DK) 

interconnect register of the board/ ics find _rec reads the . ics_find(D3DK) 

field of the HOST ID record in/ ics hostid returns the host id . ics_hostid(D3DK) 

specified number of interconnect/ ics rdwr reads or writes a . ics_rdwr(D3DK) 

register of the board in the/ ics read reads the interconnect . ics_read(D3DK) 

specified register of the board in/ ics write writes a value into the . ics_write(D3DK) 

this/ ics_hostid returns the host id field of the HOST ID record in . ics_hostid(D3DK) 

kvtoppid get physical page ID for kernel virtual address . kvtoppid(D3DK) 

phystoppid get physical page ID for physical address . phystoppid(D3DK) 

registers from a given cardslot ID /number of interconnect space . ics_rdwr(D3DK) 

a previously allocated transaction id mps_free_tid frees . mps_free_tid(D3DK) 

the host id field of the HOST ID record in this board's/ /returns . ics_hostid(D3DK) 

mps_get_tid allocates transaction ids . mps_get_tid(D3DK) 

port inb read a byte from a 8 bit 1/O . inb(D3DK) 

information info STREAMS driver and module . info(DlDK) 

event has occurred pollwakeup inform polling processes that an . pollwakeup(D3DK) 

of the queue strqget get information about a queue or band . strqget(D3DK) 

of the queue strqset change information about a queue or band . strqset(D3DK) 

drv getparm retrieve kernel state information . drv_getparm(D3DK) 

drv_setparm set kernel state information . drv_setparm(D3DK) 

info STREAMS driver and module information . info(DlDK) 

STREAMS driver and module information structure module info . module_info(D4DK) 

init initialize a device . init(D2DK) 

qinit STREAMS queue initialization structure . qinit(D4DK) 

LOCK ALLOC allocate and initialize a basic lock . LOCK_ALLOC(D3DK) 

start-up start initialize a device at system . start(D2DK) 

init initialize a device . init(D2DK) 

phalloc allocate and initialize a pollhead structure . phalloc(D3DK) 

management/ rmallocmap allocate and initialize a private space . rmallocmap(D3DK) 

RWALLOC allocate and initialize a read/write lock . RW_ALLOC(D3DK) 

SLEEP ALLOC allocate and initialize a sleep lock . SLEEP_ALLOC(D3DK) 

variable SV ALLOC allocate and initialize a synchronization . SV_ALLOC (D3DK) 

software request dma swstart initiate a DMA operation via . dma_swstart(D3X) 

/constructs a message to be sent to initiate a solicited data reply . mps_mk_solrply(D3DK) 

/ constructs a message to be sent to initiate a solicited data transfer . mps_mk_sol(D3DK) 

bit I/O port ini read a 32 bit word from a 32 . inl(D3DK) 

insq insert a message into a queue . insq(D3DK) 

insq insert a message into a queue . insq(D3DK) 

LOCK DEALLOC deallocate an instance of a basic lock . LOCK_DEALLOC(D3DK) 
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dmajpageio break up an I/O request into manageable units . dma_pageio(D3DK) 

physiock validate and issue raw I/O request . physiock(D3DK) 

uio scatter/gather 1/O request structure . uio(D4DK) 

strategy perform block I/O . strategy(D2DK) 

iovec data storage structure for I/O using uio(D4DK) . iovec(D4DK) 

iocblk STREAMS ioctl structure . iocblk(D4DK) 

ioctl control a character device . ioctl(D2DK) 

copyreq STREAMS transparent ioctl copy request structure . copyreq(D4DK) 

copyresp STREAMS transparent ioctl copy response structure . copyresp(D4DK) 

iocblk STREAMS ioctl structure . iocblk(D4DK) 

I/O using uio(D4DK) iovec data storage structure for . iovec(D4DK) 

physiock validate and issue raw I/O request . physiock(D3DK) 

specified length of time itimeout execute a function after a . itimeout(D3DK) 

external major device number itoemajor convert internal to . itoemajor(D3DK) 

between address locations in the kernel bcopy copy data . bcopy(D3DK) 

intro introduction to kernel data structures . intro(D4DK) 

intro introduction to kernel #define's . intro(D5DK) 

kmem alloc allocate space from kernel free memory . kmem_alloc(D3DK) 

allocate and clear space from kernel free memory kmem zalloc . kmem_zalloc(D3DK) 

kmem free free previously allocated kernel memory . kmem_free(D3DK) 

drv getparm retrieve kernel state information . drv_getparm(D3DK) 

drv setparm set kernel state information . drv_setparm(D3DK) 

intro introduction to kernel utility routines . intro(D3DK) 

kvtoppid get physical page ID for kernel virtual address . kvtoppid(D3DK) 

kernel free memory kmem alloc allocate space from . kmem_alloc(D3DK) 

kernel memory kmem free free previously allocated . kmem_free(D3DK) 

space from kernel free memory kmem zalloc allocate and clear . kmem_zalloc(D3DK) 

kernel virtual address kvtoppid get physical page ID for . kvtoppid(D3DK) 

max return the larger of two integers . max(D3DK) 

mps get reply len get data length for a solicited reply . mps_get_reply_len(D3DK) 

processor, after a specified length of time /on a specified . dtimeout(D3DK) 

a function after a specified length of time itimeout execute . itimeout(D3DK) 

min return the lesser of two integers . min(D3DK) 

linkblk STREAMS multiplexor link structure . linkblk(D4DK) 

blocks linkb concatenate two message . linkb(D3DK) 

structure linkblk STREAMS multiplexor link . linkblk(D4DK) 

address space for buffer page list bp mapin allocate virtual . bp_mapin(D3DK) 

address space for buffer page list bp mapout deallocate virtual . bp_mapout(D3DK) 

a buffer to the system's free list brelse return . brelse(D3DK) 

mps_free_dmabuf frees a list of data buffer descriptors . mps_free_dmabuf(D3DK) 

/returns a pointer to a list of data buffer descriptors . mps_get_dmabuf(D3DK) 

bcopy copy data between address locations in the kernel . bcopy(D3DK) 

LOCK acquire a basic lock . LOCK(D3DK) 

RW RDLOCK acquire a read/write lock in read mode . RW_RDLOCK(D3DK) 

try to acquire a read/write lock in read mode RW TRYRDLOCK 

. RW_TRYRDLOCK(D3DK) 
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mmap check virtual 
physmap obtain virtual address 
physmap free free virtual address 
integers 
bzero clear 
allocate space from kernel free 
free previously allocated kernel 
and clear space from kernel free 
puts a buffer back into the free 
mmap check virtual mapping for 
adjmsg trim bytes from a 
putbq place a 
allocb allocate a 
copyb copy a 
dupb duplicate a 
freeb free a 
rmvb remove a 
message unlinkb remove a 
msgb STREAMS 
esballoc allocate a 
linkb concatenate two 
mps_get_msgbuf allocates a 
copies user data from the 
copies user data from the 

copymsg copy a 
test whether a message is a data 
dupmsg duplicate a 
free_rtn STREAMS driver's 
freemsg free a 
getq get the next 
rmvq remove a 
/ mps_msg_isreq macros used to decode 
in a stream qreply send a 
insq insert a 
datamsg test whether a 
message pcmsg test whether a 
used to decode message handler 
return number of bytes of data in a 
msgpullup concatenate bytes in a 
putq put a 
print display a driver 
cmn_err display an error 
a message is a priority control 
canput test for room in a 
rmvb remove a message block from a 
putctl send a control 


mapping for memory-mapped device 

mapping for physical addresses . 

mapping for physical addresses . 

max return the larger of two . 

memory for a given number of bytes 

memory kmem alloc . 

memory kmem free . 

memory kmem zalloc allocate . 

memory pool mps free msgbuf . 

memory-mapped device . 

message . 

message at the head of a queue . 

message block . 

message block . 

message block . 

message block .. 

message block from a message . 

message block from the head of a . 

message block structure . 

message block using an/ . 

message blocks . 

message buffer . 

message buffer mps get soldata . 

message buffer mps_get_unsoldata 


message . 

message datamsg . 

message . 

message free routine structure . 

message . 

message from a queue . 

message from a queue . 

message handler message . 

message in the opposite direction 

message into a queue . 

message is a data message . 

message is a priority control . 

message / mps msg isreq macros 

message msgdsize . 

message . 

message on a queue . 

message on the system console . 

message or panic the system .. 

message pcmsg test whether . 

message queue . 

message . 

message to a queue . 


. mmap(D2DK) 

. physmap(D3DK) 

. physmap_free(D3DK) 

. max(D3DK) 

. bzero(D3DK) 

. kmem_alloc(D3DK) 

. kmem_free(D3DK) 

. kmem_zalloc(D3DK) 

.. mps_free_msgbuf(D3DK) 

. mmap(D2DK) 

. adjmsg(D3DK) 

. putbq(D3DK) 

. allocb(D3DK) 

. copyb(D3DK) 

. dupb(D3DK) 

. freeb(D3DK) 

. rmvb(D3DK) 

. unlinkb(D3DK) 

. msgb(D4DK) 

. esballoc(D3DK) 

. linkb(D3DK) 

... mps_get_msgbuf(D3DK) 
.... mps_get_soldata(D3DK) 

mps_get_unsoldata(D3DK) 

. copymsg(D3DK) 

. datamsg(D3DK) 

. dupmsg(D3DK) 

. free_rtn(D4DK) 

. freemsg(D3DK) 

. getq(D3DK) 

. rmvq(D3DK) 

. mps_msg(D3DK) 

. qreply(D3DK) 

. insq(D3DK) 

. datamsg(D3DK) 

. pcmsg(D3DK) 

. mps_msg(D3DK) 

. msgdsize(D3DK) 

. msgpullup (D3DK) 

. putq(D3DK) 

. print(D2DK) 

. cmn_err(D3DK) 

. pcmsg(D3DK) 

. canput(D3DK) 

. rmvb(D3DK) 

. putctl(D3DK) 
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solicited data in fragments when/ 

messages that are not part of any/ 
data that is not part of any/ 

received request that is part of a/ 

messages for transmission and sets/ 

opened channel 

data buffer descriptors 

into the free memory pool 

allocated transaction id 
a list of data buffer descriptors 

buffer 

for a solicited reply 
from the message buffer 
ids 

from the message buffer 

grant in response to a buffer/ 

broadcast message to be sent 
reject in response to a buffer/ 

be sent to initiate a solicited/ 
to be sent to initiate a solicited/ 

unsolicited message to be sent 
unsolicited reply message to be/ 

mps_msg_getmsgtyp, / 
/mps_msg_getmsgtyp, 

/mps_msg_getbrlen, mps_msg_getreqid, 
mps msg: mps_msg_getsrcmid, 
/mps_msg_getbrlen, 

mps_msg_getmsgtyp,/ mps_msg: 
/mps_msg_getreqid, mps_msg_getlsnid. 


mps AMPreceive frag receives 

. mps_AMPreceive_frag(D3DK) 

mps AMPsend sends unsolicited . mps_AMPsend(D3DK) 

mps_AMPsend_data sends solicited 

. mps_AMPsend_data(D3DK) 

mps AMPsend reply replies to a 

. mps_AMPsend_reply(D3DK) 

mps_AMPsend_rsvp queues request 

. mps_AMPsend_rsvp(D3DK) 

mps close chan closes a previously 

. mps_close_chan(D3DK) 

mps free dmabuf frees a list of 

. mps_free_dmabuf(D3DK) 

mps free msgbuf puts a buffer back 

. mps_free_msgbuf(D3DK) 

mps free tid frees a previously . mps_free_tid(D3DK) 

mps get dmabuf returns a pointer to 

. mps_get_dmabuf(D3DK) 

mps get msgbuf allocates a message 

. mps_get_msgbuf(D3DK) 

mps get reply len get data length 

. mps_get_reply_len(D3DK) 

mps get soldata copies user data 

. mps_get_soldata(D3DK) 

mps_get_tid allocates transaction . mps_get_tid(D3DK) 

mps get imsoldata copies user data 

. mps_get_unsoldata(D3DK) 

mps mk bgrant construct a buffer 

. mps_mk_bgrant(D3DK) 

mps mk brdcst constructs a . mps_mk_brdcst(D3DK) 

mps mk breject construct a buffer 

. mps_mk_breject(D3DK) 

mps mk sol constructs a message to . mps_mk_sol(D3DK) 

mps mk solrply constructs a message 

. mps_mk_solrply(D3DK) 

mps mk unsol constructs an . mps_mk_unsol(D3DK) 

mps mk unsolrply constructs a 

. mps_mk_unsolrply(D3DK) 

mps msg: mps_msg_getsrcmid, . mps_msg(D3DK) 

mps_msg_getbrlen, mps_msg_getreqid, / 

. mps_msg(D3DK) 

mps msg getlsnid,/ . mps_msg(D3DK) 

mps msg getmsgtyp,/ . mps_msg(D3DK) 

mps msg getreqid, mps msg getlsnid, / 

. mps_msg(D3DK) 

mps_msg_getsrcmid, . mps_msg(D3DK) 

mps msg getsrcpid,/ . mps_msg(D3DK) 
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request dma swsetup program a DMA operation for a subsequent software . dma_swsetup(D3X) 

it /stop software-initiated DMA operation on a channel and release . dma_stop(D3X) 

dma swstart initiate a DMA operation via software request . dma_swstart(D3X) 

qreply send a message in the opposite direction in a stream . qreply(D3DK) 

stroptions stream head option structure . stroptions(D4DK) 

partner queue OTHERQ get pointer to queue's . OTHERQ(D3DK) 

port outb write a byte to an 8 bit I/O . outb(D3DK) 

32 bit I/O port outi write a 32 bit long word to a . outl(D3DK) 

/ data that corresponds to an outstanding buffer request . mps_AMPreceive(D3DK) 

16 bit I/O port outw write a 16 bit short word to a . outw(D3DK) 

kvtoppid get physical page ID for kernel virtual address . kvtoppid(D3DK) 

phystoppid get physical page ID for physical address . phystoppid(D3DK) 

virtual address space for buffer page list bp mapin allocate . bp_mapin(D3DK) 

virtual address space for buffer page list bp mapout deallocate . bp_mapout(D3DK) 

getnextpg get next page pointer . getnextpg(D3DK) 

pptophys convert page pointer to physical address . pptophys(D3DK) 

convert size in bytes to size in pages (round down) btop . btop(D3DK) 

convert size in bytes to size in pages (round up) btopr . btopr(D3DK) 

ptob convert size in pages to size in bytes . ptob(D3DK) 

cmn err display an error message or panic the system . cmn_err(D3DK) 

a control message with a one-byte parameter to a queue putctll send . putctl(D3DK) 

a control message with a one byte parameter to a queue /send . putnextctl(D3DK) 

to a received request that is part of a request-response/ /replies 

. mps_AMPsend_reply(D3DK) 

unsolicited messages that are not part of any request-response/ /sends 

. mps_AMPsend(D3DK) 

/sends solicited data that is not part of any request-response/ 

. mps_AMPsend_data(D3DK) 

OTHERQ get pointer to queue's partner queue . OTHERQ(D3DK) 

priority control message pcmsg test whether a message is a . pcmsg(D3DK) 

unbufcall cancel a pending bufcall request . unbufcall(D3DK) 

biowait suspend processes pending completion of block I/O . biowait(D3DK) 

strategy perform block I/O . strategy(D2DK) 

pollhead structure phalloc allocate and initialize a . phalloc(D3DK) 

phfree free a pollhead structure . phfree(D3DK) 

phystoppid get physical page ID for physical address . phystoppid(D3DK) 

pptophys convert page pointer to physical address . pptophys(D3DK) 

vtop convert virtual address to physical address . vtop(D3DK) 

obtain virtual address mapping for physical addresses physmap . physmap(D3DK) 

free virtual address mapping for physical addresses physmap free . physmap_free(D3DK) 

address kvtoppid get physical page ID for kernel virtual . kvtoppid(D3DK) 

address phystoppid get physical page ID for physical . phystoppid(D3DK) 

request physiock validate and issue raw I/O . physiock(D3DK) 

mapping for physical addresses physmap obtain virtual address . physmap (D3DK) 

mapping for physical addresses physmap free free virtual address . physmap_free(D3DK) 

physical address phystoppid get physical page ID for . phystoppid(D3DK) 

queue putbq place a message at the head of a . putbq(D3DK) 
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determine whether credentials are privileged drvjpriv . drv_priv(D3DK) 

put call a put procedure . put(D3DK) 

intr process a device interrupt . intr(D2DK) 

number of clock ticks delay delay process execution for a specified . delay(D3DK) 

proc ref obtain a reference to a process for signaling . proc_ref(D3DK) 

proc signal send a signal to a process . proc_signal(D3DK) 

proc unref release a reference to a process . proc_unref(D3DK) 

SV SIGNAL wake up one process sleeping on a/ . SV_SIGNAL(D3DK) 

buffer after block I/O and wakeup processes biodone release . biodone(D3DK) 

block I/O biowait suspend processes pending completion of . biowait(D3DK) 

SV BROADCAST wake up all processes sleeping on a/ . SV_BROADCAST(D3DK) 

occurred pollwakeup inform polling processes that an event has . poll wakeup (D3DK) 

/execute a function on a specified processor, after a specified length/ . dtimeout(D3DK) 

spl block/allow interrupts on a processor . spl(D3DK) 

process for signaling proc ref obtain a reference to a . proc_ref(D3DK) 

process proc_signal send a signal to a . proc_signal(D3DK) 

process proc imref release a reference to a . proc_unref(D3DK) 

subsequent hardware/ dma_prog program a DMA operation for a . dma_prog(D3X) 

subsequent software/ dma_swsetup program a DMA operation for a . dma_swsetup(D3X) 

in bytes ptob convert size in pages to size . ptob(D3DK) 

putq put a message on a queue . putq(D3DK) 

qprocsoff disable put and service routines . qprocsoff(D3DK) 

qprocson enable put and service routines . qprocson(D3DK) 

put call a put procedure . put(D3DK) 

put call a put procedure . put(D3DK) 

preceding queue put receive messages from the . put(D2DK) 

of a queue putbq place a message at the head . putbq(D3DK) 

queue putctl send a control message to a . putctl(D3DK) 

a one-byte parameter to a queue putctll send a control message with . putctl(D3DK) 

queue putnext send a message to the next . putnext(D3DK) 

to a queue putnextctl send a control message . putnextctl(D3DK) 

with a one byte parameter to a/ putnextctll send a control message . putnextctl(D3DK) 

putq put a message on a queue . putq(D3DK) 

memory pool mps free msgbuf puts a buffer back into the free . mps_free_msgbuf(D3DK) 

routine to be run qenable schedule a queue's service . qenable(D3DK) 

structure qinit STREAMS queue initialization . qinit(D4DK) 

routines qprocsoff disable put and service . qprocsoff(D3DK) 

routines qprocson enable put and service . qprocson(D3DK) 

opposite direction in a stream qreply send a message in the . qreply(D3DK) 

on a queue qsize find the number of messages . qsize(D3DK) 

available SLEEP LOCKAVAIL query whether a sleep lock is 

. SLEEP_LOCKAVAIL(D3DK) 

by the caller SLEEP LOCKOWNED query whether a sleep lock is held 

. SLEEP_LOCKOWNED(D3DK) 

canput test for room in a message queue . canput(D3DK) 

flushq flush messages on a queue . flushq(D3DK) 

noenable prevent a queue from being scheduled . noenable(D3DK) 
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RW TRYRDLOCK try to acquire a 
RW_TRYWRLOCK try to acquire a 

RW_WRLOCK acquire a 
RW_ALLOC allocate and initialize a 
deallocate an instance of a 
RW UNLOCK release a 
register of the board in/ ics_find 
queue put 

mps_AMPsend_reply replies to a 

fragments when/ mps_AMPreceive_frag 
corresponds to an/ mps_AMPreceive 
space is not available at the 

/and sets up table entries for 
a DMA channel dma disable disable 
a DMA channel dma enable enable 
/ the host id field of the HOST ID 
signaling proc ref obtain a 
proc unref release a 
/_rec reads the interconnect 
ics_read reads the interconnect 
/writes a value into the specified 
/number of interconnect space 
mps mk breject construct a buffer 
UNLOCK 
RWUNLOCK 
procunref 
SLEEPUNLOCK 
wakeup processes biodone 
DMA operation on a channel and 
close 

message rmvb 
head of a message unlinkb 
rmvq 
buffer 
port to buffer 
port to buffer 
is part of a/ mps_AMPsend_reply 

/constructs a unsolicited 
up table entries for reception of 
get data length for a solicited 
sent to initiate a solicited data 

an I/O port 


read/write lock in read mode . RW_TRYRDLOCK(D3DK) 

read/write lock in write mode 

. RW_TRYWRLOCK(D3DK) 

read/write lock in write mode . RW_WRLOCK(D3DK) 

read/write lock . RW_ALLOC(D3DK) 

read/write lock RW_DEALLOC . RW_DEALLOC(D3DK) 

read/write lock . RW_UNLOCK(D3DK) 

_rec reads the interconnect . ics_find(D3DK) 

receive messages from the preceding . put(D2DK) 

received request that is part of a/ 

. mps_AMPsend_reply(D3DK) 

receives solicited data in . mps_AMPreceive_frag(D3DK) 

receives solicited data that . mps_AMPreceive(D3DK) 

receiving agent / when buffer 

. mps_AMPreceive_frag(D3DK) 

reception of reply messages . mps_AMPsend_rsvp(D3DK) 

recognition of hardware requests on . dma_disable(D3X) 

recognition of hardware requests on . dma_enable(D3X) 

record in this board's interconnect/ . ics_hostid(D3DK) 

reference to a process for . proc_ref(D3DK) 

reference to a process . proc_unref(D3DK) 

register of the board in the/ . ics_find(D3DK) 

register of the board in the/ . ics_read(D3DK) 

register of the board in the/ . ics_write(D3DK) 

registers from a given cardslot ID . ics_rdwr(D3DK) 

reject in response to a buffer/ . mps_mk_breject(D3DK) 

release a basic lock . UNLOCK(D3DK) 

release a read/write lock . RW_UNLOCK(D3DK) 

release a reference to a process . proc_unref(D3DK) 

release a sleep lock . SLEEP_UNLOCK(D3DK) 

release buffer after block I/O and . biodone(D3DK) 

release it /stop software-initiated . dma_stop(D3X) 

relinquish access to a device . close(D2DK) 

remove a message block from a . rmvb(D3DK) 

remove a message block from the . unlinkb(D3DK) 

remove a message from a queue . rmvq(D3DK) 

repinsb read bytes from I/O port to . repinsb(D3DK) 

repinsd read 32 bit words from I/O . repinsd(D3DK) 

repinsw read 16 bit words from I/O . repinsw(D3DK) 

replies to a received request that 

. mps_AMPsend_reply(D3DK) 

reply message to be sent . mps_mk_unsolrply(D3DK) 

reply messages /and sets . mps_AMPsend_rsvp(D3DK) 

reply mps_get_reply_len . mps_get_reply_len(D3DK) 

reply / constructs a message to be 

. mps_mk_solrply(D3DK) 

repoutsb write bytes from buffer to . repoutsb(D3DK) 
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size in bytes to size in pages 
STREAMS driver's message free 
qenable schedule a queue's service 
introduction to driver entry point 
introduction to kernel utility 
intro introduction to DMA utility 
qprocsoff disable put and service 
qprocson enable put and service 
mps_AMPcancel cancels an ongoing 
a queue's service routine to be 
read/write lock 
of a read/write lock 

in read mode 
read/write lock in read mode 
read/write lock in write mode 


in write mode 
type 

structure uio 
to be run qenable 
noenable prevent a queue from being 

putctl 

putnextctl 

byte parameter to a/ putnextctll 
one-byte parameter to a/ putctll 
direction in a stream qreply 
putnext 
proc_signal 

part of any/ mps AMPsend data 

not part of any/ mps AMPsend 

a broadcast message to be 
an unsolicited message to be 
a unsolicited reply message to be 

reply / constructs a message to be 
/ constructs a message to be 
srv 

qenable schedule a queue's 
qprocsoff disable put and 


(round up) btopr convert . 

routine structure free rtn . 

routine to be run . 

routines intro . 

routines intro . 

routines . 

routines . 

routines . 

rsvp transaction . 

run qenable schedule ... 

RW ALLOC allocate and initialize a 
RW DEALLOC deallocate an instance 


. btopr(D3DK) 

. free_rtn(D4DK) 

. qenable(D3DK) 

. intro(D2DK) 

. intro(D3DK) 

. intro(D3X) 

. qprocsoff(D3DK) 

. qprocson(D3DK) 

mps_AMPcancel(D3DK) 

. qenable(D3DK) 

. RW_ALLOC(D3DK) 


. RW_DEALLOC(D3DK) 

RW RDLOCK acquire a read/write lock 

. RW_RDLOCK(D3DK) 

RW TRYRDLOCK try to acquire a 

. RW_TRYRDLOCK(D3DK) 

RW_TRYWRLOCK try to acquire a 

. RW_TRYWRLOCK(D3DK) 

RW_UNLOCK release a read/write lock 

. RW_UNLOCK(D3DK) 

RW_WRLOCK acquire a read/write lock 
. RW_WRLOCK(D3DK) 


SAMESTR test if next queue is same . SAMESTR(D3DK) 

scatter/gather I/O request . uio(D4DK) 

schedule a queue's service routine . qenable(D3DK) 

scheduled . noenable(D3DK) 

send a control message to a queue . putctl(D3DK) 

send a control message to a queue . putnextctl(D3DK) 

send a control message with a one . putnextctl(D3DK) 

send a control message with a . putctl(D3DK) 

send a message in the opposite . qreply(D3DK) 

send a message to the next queue . putnext(D3DK) 

send a signal to a process . proc_signal(D3DK) 

sends solicited data that is not 


. mps_AMPsend_data(D3DK) 

sends unsolicited messages that are 

. mps_AMPsend(D3DK) 

sent mps mk brdcst constructs . mps_mk_brdcst(D3DK) 

sent mps mk imsol constructs . mps_mk_unsol(D3DK) 

sent mps mk unsolrply constructs 

. mps_mk_unsolrply(D3DK) 

sent to initiate a solicited data . mps_mk_solrply(D3DK) 

sent to initiate a solicited data/ . mps_mk_sol(D3DK) 

service queued messages . srv(D2DK) 

service routine to be run . qenable (D3DK) 

service routines . qprocsoff(D3DK) 
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sleep lock 


board types in the designated 
of the board in the specified 
of the board in the specified 
of the board in the specified 
a DMA operation for a subsequent 
initiate a DMA operation via 
a channel and/ dma stop stop 
mps AMPreceive frag receives 

a message to be sent to initiate a 
an/ mps AMPreceive receives 

any/ mps AMPsend data sends 

a message to be sent to initiate a 
get data length for a 

ureadc copy a character to 
uwritec return a character from 
bp mapin allocate virtual address 
/deallocate virtual address 
management map rmalloc allocate 
management/ rmalloc wait allocate 
kmem alloc allocate 
kmem zalloc allocate and clear 
record in this board's interconnect 
management map rmfree free 
/data in fragments when buffer 

allocate space from a private 
allocate and initialize a private 
allocate space from a private 

rmfree free space into a private 
rmfreemap free a private 
/a specified number of interconnect 
drv_usecwait busy-wait for 
on a specified processor, after a 
itimeout execute a function after a 
delay delay process execution for a 
space/ ics rdwr reads or writes a 


SLEEP LOCK SIG acquire a sleep lock 

. SLEEP_LOCK_SIG(D3DK) 

SLEEP TRYLOCK try to acquire a 

. SLEEP_TRYLOCK(D3DK) 

SLEEP_UNLOCK release a sleep lock 

. SLEEP_UNLOCK(D3DK) 


slot /checks for certain . ics_agent_cmp(D3DK) 

slot /the interconnect register . ics_find(D3DK) 

slot /the interconnect register . ics_read(D3DK) 

slot /into the specified register . ics_write(D3DK) 

software request /program . dma_swsetup(D3X) 

software request dma swstart . dma_swstart(D3X) 

software-initiated DMA operation on . dma_stop(D3X) 

solicited data in fragments when/ 

. mps_AMPreceive_frag(D3DK) 

solicited data reply /constructs . mps_mk_solrply(D3DK) 

solicited data that corresponds to 


. mps_AMPreceive(D3DK) 

solicited data that is not part of 


. mps_AMPsend_data(D3DK) 

solicited data transfer /constructs . mps_mk_sol(D3DK) 

solicited reply mps get reply len 


mps_get_reply_len(D3DK) 


space described by uio(D4DK)/ . ureadc(D3DK) 

space described by uio(D4DK)/ . uwritec(D3DK) 

space for buffer page list . bp_mapin(D3DK) 

space for buffer page list . bp_mapout(D3DK) 

space from a private space . rmalloc(D3DK) 

space from a private space . rmalloc_wait(D3DK) 

space from kernel free memory . kmem_alloc(D3DK) 

space from kernel free memory . kmem_zalloc(D3DK) 

space /host id field of the HOST ID . ics_hostid(D3DK) 

space into a private space . rmfree(D3DK) 

space is not available at the/ 

. mps_AMPreceive_frag(D3DK) 

space management map rmalloc . rmalloc(D3DK) 

space management map rmallocmap . rmallocmap(D3DK) 


space management map rmalloc wait 


. rmalloc_wait(D3DK) 

space management map . rmfree(D3DK) 

space management map . rmfreemap(D3DK) 

space registers from a given/ . ics_rdwr(D3DK) 

specified interval . drv_usecwait(D3DK) 

specified length of time / function . dtimeout(D3DK) 

specified length of time . itimeout(D3DK) 

specified number of clock ticks . delay(D3DK) 

specified number of interconnect . ics_rdwr(D3DK) 
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driver's message free routine structure free rtn STREAMS . free_rtn(D4DK) 

iocblk STREAMS ioctl structure . iocblk(D4DK) 

linkblk STREAMS multiplexor link structure . linkblk(D4DK) 

driver and module information structure module info STREAMS . module_info(D4DK) 

msgb STREAMS message block structure . msgb(D4DK) 

allocate and initialize a pollhead structure phalloc . phalloc(D3DK) 

phfree free a pollhead structure . phfree(D3DK) 

qinit STREAMS queue initialization structure . qinit(D4DK) 

queue STREAMS queue structure . queue(D4DK) 

driver and module declaration structure streamtab STREAMS . streamtab(D4DK) 

stroptions stream head option structure . stroptions(D4DK) 

uio scatter/gather I/O request structure . uio(D4DK) 

uiomove copy data using uio(D4DK) structure . uiomove(D3DK) 

to space described by uio(D4DK) structure ureadc copy a character . ureadc(D3DK) 

from space described by uio(D4DK) structure /return a character . uwritec(D3DK) 

intro introduction to kernel data structures . intro(D4DK) 

intro introduction to DMA data structures . intro(D4X) 

strlog submit messages to the log driver . strlog(D3DK) 

/program a DMA operation for a subsequent hardware request . dmajprog(D3X) 

/program a DMA operation for a subsequent software request . dma_swsetup(D3X) 

completion of block I/O biowait suspend processes pending . biowait(D3DK) 

synchronization variable SV ALLOC allocate and initialize a . SV_ALLOC(D3DK) 

sleeping on a synchronization/ SV BROADCAST wake up all processes 

. SV_BROADCAST(D3DK) 

of a synchronization variable SV_DEALLOC deallocate an instance 

. SV_DEALLOC(D3DK) 

sleeping on a synchronization/ SV_SIGNAL wake up one process . SV_SIGNAL(D3DK) 

variable SV WAIT sleep on a synchronization . SV_WAIT(D3DK) 

synchronization variable SV WAIT SIG sleep on a . SV_WAIT_SIG(D3DK) 

SV_ALLOC allocate and initialize a synchronization variable . SV_ALLOC(D3DK) 

/wake up all processes sleeping on a synchronization variable . SV_BROADCAST(D3DK) 

/deallocate an instance of a synchronization variable . SV_DEALLOC(D3DK) 

wake up one process sleeping on a synchronization variable SV SIGNAL 

. SV_SIGNAL(D3DK) 

SV WAIT sleep on a synchronization variable . SV_WAIT(D3DK) 

SV WAIT SIG sleep on a s)mchronization variable . SV_WAIT_SIG(D3DK) 

an error message or panic the system cmn err display . cmn_err(D3DK) 

display a driver message on the system console print . print(D2DK) 

halt shut down the driver when the system shuts down . halt(D2DK) 

start initialize a device at system start-up . start(D2DK) 

brelse return a buffer to the system's free list . brelse(D3DK) 

reply/ /for transmission and sets up table entries for reception of . mps_AMPsend_rsvp(D3DK) 

specified priority/ bcanputnext test for flow control in a . bcanputnext(D3DK) 

canputnext test for flow control in a stream . canputnext(D3DK) 

priority band bcanput test for flow control in specified . bcanput(D3DK) 

canput test for room in a message queue . canput(D3DK) 

SAMESTR test if next queue is same type . SAMESTR(D3DK) 
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sent mps mk unsolrply constructs a unsolicited reply message to be 

. mps_mk_unsolrply(D3DK) 


request untimeout cancel previous timeout . untimeout(D3DK) 

in bytes to size in pages (round up) btopr convert size . btopr(D3DK) 

described by uio(D4DK) structure ureadc copy a character to space . ureadc(D3DK) 

copy data from a driver buffer to a user buffer copyout . copyout(D3DK) 

copyin copy data from a user buffer to a driver buffer . copyin(D3DK) 

mps get soldata copies user data from the message buffer 


. mps_get_soldata(D3DK) 

mps get unsoldata copies user data from the message buffer 

. mps_get_unsoldata(D3DK) 


esballoc allocate a message block using an externally-supplied buffer . esballoc(D3DK) 

data storage structure for I/O using uio(D4DK) iovec . iovec(D4DK) 

uiomove copy data using uio(D4DK) structure . uiomove(D3DK) 

intro introduction to kernel utility routines . intro(D3DK) 

intro introduction to DMA utility routines . intro(D3X) 

space described by uio(D4DK)/ uwritec return a character from . uwritec(D3DK) 

physiock validate and issue raw I/O request . physiock(D3DK) 

of the board in/ ics_write writes a value into the specified register . ics_write(D3DK) 

and initialize a synchronization variable SV_ALLOC allocate . SV_ALLOC(D3DK) 

sleeping on a synchronization variable /wake up all processes . SV_BROADCAST(D3DK) 

an instance of a synchronization variable SV_DEALLOC deallocate . SV_DEALLOC(D3DK) 

sleeping on a synchronization variable /wake up one process . SV_SIGNAL(D3DK) 

SV_WAIT sleep on a synchronization variable . SV_WAIT(D3DK) 

sleep on a synchronization variable SV_WAIT_SIG . SV_WAIT_SIG(D3DK) 

ASSERT verify assertion . ASSERT(D3DK) 

initiate a DMA operation via software request dma_swstart . dma_swstart(D3X) 

get physical page ID for kernel virtual address kvtoppid . kvtoppid(D3DK) 

physical addresses physmap obtain virtual address mapping for . physmap(D3DK) 

physical/ physmap free free virtual address mapping for . physmap_free(D3DK) 

page list bp mapin allocate virtual address space for buffer . bp_mapin(D3DK) 

page list bp mapout deallocate virtual address space for buffer . bp_mapout(D3DK) 

vtop convert virtual address to physical address . vtop(D3DK) 

device mmap check virtual mapping for memory-mapped . mmap(D2DK) 

physical address vtop convert virtual address to . vtop(D3DK) 

synchronization/ SV BROADCAST wake up all processes sleeping on a 

. SV_BROADCAST(D3DK) 

synchronization variable SV SIGNAL wake up one process sleeping on a . SV_SIGNAL(D3DK) 

release buffer after block I/O and wakeup processes biodone . biodone(D3DK) 

datamsg test whether a message is a data message . datamsg(D3DK) 

control message pcmsg test whether a message is a priority . pcmsg(D3DK) 

SLEEP LOCKAVAIL query whether a sleep lock is available 


. SLEEP_LOCKAVAIL(D3DK) 

caller SLEEP LOCKOWNED query whether a sleep lock is held by the 

. SLEEP_LOCKOWNED(D3DK) 


drv_priv determine whether credentials are privileged . drv_priv(D3DK) 

bioerror manipulate error field within a buffer header . bioerror(D3DK) 
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devflag(DID) 


DDI 


devflag(DID) 


NAME 

devf lag - driver flags 

SYNOPSIS 

#include <sys/conf.h> 
int prefixd&vfleig = 0; 

DESCRIPTION 

Every driver must define a global integer containing a bitmask of flags that indi¬ 
cate its characteristics to the system. Tbie valid flags that may be set are: 

D_nMA The driver does DMA (Direct Memory Access). 

D_TAPE The driver controls a tape device (mount read-only). 

D_NOBRKUP The driver understands the B_PAGElO flag in the buffer header (the 
I/O job is not broken up along page boundaries into multiple jobs 
by the kernel). 

D_MP The driver is multithreaded (it handles its own locking and serializa¬ 

tion). 

If no flags are set for the driver, then pr^'xdevf lag should be set to 0. 

SEE ALSO 

Integrated Software Development Guide 
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DDI/DKI 


prefix (D1DK) 


NAME 

prefix - driver prefix 

SYNOPSIS 

int prefixclose () ; 
int prefixopen () ; 

DESCRIPTION 

Every driver must define a unique prefix, whose maximum length is 
implementation-defined. The prefix is usually specified in a configuration file. 
Driver entry points names are created by concatenating the driver prefix with the 
name for the entry point. This enables driver entry points to be identified by 
configuration software and decreases the possibility of global symbol collisions in 
the kernel. 

SEE ALSO 

devflag(DlD), info(DlD), chpoll(D2DK), close(D2DK), halt(D2D), 
init(D2D), intr(D2D), ioctl(D2DK), inmap(D2DK), open(D2DK), print(D2DK), 
put(D2DK), read(D2DK), size(D2DK), srv(D2DK), start(D2DK), 
strategy(D2DK), write(D2DK) 

EXAMPLE 

An ETHERNET driver might use a driver prefix of "en." It would define the fol¬ 
lowing entry points: enclose, eninit, enintr, enopen, enwput, enrsrv, and 
enwsrv. It would also define the data symbols endevf lag and eninfo. 
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DDI/DKI 


chpoll(D2DK) 


NAME 

chpoll - poll entry point for a non-STREAMS character driver 

SYNOPSIS 

#include <sys/poll.h> 


int prc^'xchpoll (dev_t dev, short events, int anyyet, short *reventsp, 

struct pollhead **phpp ); 

ARGUMENTS 

dev The device number for the device to be polled. 

events Mask (bit-wise OR) indicating the events being polled. Valid events 
are: 


anyyet 


POLLIN 

POLLOUT 

POLLPRI 

POLLHUP 

POLLERR 

POLLRDNORM 

POLLWRNORM 

POLLRDBAND 

POLLWRBAND 


Data are available to be read (either normal or out- 
of-band). 

Data may be written without blocking. 

High priority data are available to be read. 

A device hangup. 

A device error. 

Normal data are available to be read. 

Normal data may be written without blocking (same 
as POLLOUT). 

Out-of-band data are available to be read. 
Out-of-band data may be written without blocking. 


A flag that indicates whether the driver should return a pointer to its 
pollhead structure to the caller. 


reventsp A pointer to a bitmask of the returned events satisfied. 

phpp A pointer to a pointer to a pollhead structure (defined in 
sys/poll.h.) 

DESCRIPTION 

The chpoll entry point indicates whether certain I/O events have occurred on a 
given device. It must be provided by any non-STREAMS character device driver 
that wishes to support polling [see poll(2)]. 

A driver that supports polling must provide a pollhead structure for each minor 
device supported by the driver. The driver must use phalloc(D3DK) to allocate 
the pollhead structure. It can be freed later, if necessary, with phfree(D3DK). 
The definition of the pollhead structure is not included in the DDI/DKI, and can 
change across releases. It should be treated as a "black box" by the driver; none 
of its fields may be referenced. Drivers should not depend on the size of the 
pollhead structure. 


The driver must implement the polling discipline itself. Each time the driver 
detects a pollable event, it should call pollwakeup(D3DK), passing to it the event 
that occurred and the address of the pollhead structure associated with the 
device. Note that pollwakeup should be called with only one event at a time. 
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DDI/DKI 


close (D2DK) 


NAME 

close - relinquish access to a device 

SYNOPSIS [Block and Character] 

#include <sys/types.h> 

#include <sys/file.h> 
ttinclude <sys/ermo.h> 

#include <sys/open.h> 

#include <sys/cred.h> 

#include <sys/ddi.h> 

int prefixclose {dev_t dev, int flag, int otyp, cred_t *crp ); 

ARGUMENTS 

dev Device number. 

flag File status flag. Possible flag values and their definitions can be found 

in open(D2DK). 

otyp Parameter supplied so that the driver can determine how many times 

a device was opened and for what reasons. The values are mutually 
exclusive. 

OTYP_BLK Close was through block interface for the device. 

OTYP_CHR Close was through the raw/character interface for the 
device. 

OTYP_LYR Close a layered device. This flag is used when one 
driver calls another driver's close routine. 


crp Pointer to the user credential structure. 

SYNOPSIS [STREAMS] 

#include <sys/types.h> 

#include <sys/stream.h> 
ttinclude <sys/file.h> 

#include <sys/ermo.h> 

#include <sys/cred.h> 

#include <sys/ddi.h> 


int prefixclose *q, Int flag, cred_t *crp); 

ARGUMENTS 

q Pointer to queue used to reference the read side of the driver. 

flag File status flag. 

crp Pointer to the user credential structure. 

DESCRIPTION 

The close routine ends the connection between the user process and the device, 
and prepares the device (hardware and software) so that it is ready to be opened 
again. 

For OTYP_BLK and OTYP_CHR, a device may be opened simultaneously by multiple 
processes and the driver open routine is called for each open, but the kernel will 
only call the close routine when the last process using the device issues a 
close(2) system call or exits. 
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RETURN VALUE 

The close routine should return 0 for success, or the appropriate error number. 
Refer to ermos(D5DK) for a list of DDI/DKI error numbers. Return errors 
rarely occur, but if a failure is detected, the driver should still close the device 
and then decide whether the severity of the problem warrants displaying a mes¬ 
sage on the console. 

SEE ALSO 

open(D2DK), drv__priv(D3DK), qprocsof f (D3DK), uiibufcall(D3DK), 
untimeout(D3DK), queue(D4DK), ermos(D5DK) 
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NAME 

init - initialize a device 

SYNOPSIS 

void prefixinit (); 

DESCRIPTION 

init and start(D2DK) routines are used to initialize drivers and the devices 
they control, init routines are executed during system initialization, and can be 
used in drivers that do not require system services to be initialized, start rou¬ 
tines are executed after system services are enabled. 

init routines can perform functions such as: 

allocating memory for private buffering schemes 
mapping a device into virtual address space 

initializing hardware (for example, system generation or resetting the 
board) 

Functions that may result in the caller sleeping, or that require user context, such 
as SV_WAIT(D3DK), may not be called. Any function that provides a flag to 
prevent it from sleeping must be called such that the function does not sleep. 
Also, init routines are executed before interrupts are enabled. 

The following kernel fxmctions can be called from the driver's init routine: 


ASSERT 

drv_usectohz 

physmap 

bcopy 

drv_usecwait 

physmap_free 

btop/btopr 

etoimajor 

repinsb/repins1/ 

bzero 

getemajor 

repinsw 

cinn_err 

geteminor 

repout sb/repouts 

dina_di sable 

getmajor 

repoutsw 

dina_enable 

getminor 

rmalloc 

(3ina_free_buf 

inb/inl/inw 

rtnallocmap 

dina_free_cb 

itoemajor 

rmfreemap 

dma get best mode 

kmem_alloc 

rmfree 

dma get buf 

kmem_free 

RWLOCK_ALLOC 

dina_get_cb 

kmem_zalloc 

SLEEP_ALIiCX: 

dina_prog 

IiOCK_ALLOC 

SV_ALLOC 

dina_stop 

makedevice 

vtop 

dina_swsetup 

max/min 


dina_swstart 

outb/outl/outw 


drv_getparm 

phalloc 


drv_hztousec 

phfree 



NOTES 

This entry point is optional. 

RETURN VALUE 

None. 

SEE ALSO 

start (D2DK) 
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In addition, the functions of an intr routine are device dependent. You should 
know the exact chip set that produces the interrupt for your device. You need to 
know the exact bit patterns of the device's control and status register and how 
data is transmitted into and out of your computer. These specifics differ for 
every device you access. 

The intr routine for an intelligent controller that does not use individual inter¬ 
rupt vectors for each subdevice must access the completion queue to determine 
which subdevice generated the interrupt. It must also update the status informa¬ 
tion, set/clear flags, set/clear error indicators, and so forth to complete the han¬ 
dling of a job. The code should also be able to handle a spurious completion 
interrupt identified by an empty completion queue. When the routine finishes, it 
should advance the unload pointer to the next entry in the completion queue. 

If the driver called biowait(D3DK) or SV_WAIT(D3DK) to await the completion of 
an operation, the intr routine must call biodone(D3DK) or SV_SIGNAL(D3DK) to 
signal the process to resume. 

The interrupt routine runs at the processor level associated with the interrupt 
level for the given device. Lower priority interrupts are deferred while the inter¬ 
rupt routine is active. Certain processor levels can block different interrupts. See 
spl(D3D) for more information. 

NOTES 

This entry point is only required for those drivers that interface to hardware that 
interrupts the host computer. It is not used with software drivers. 

The intr routine must never: 
use functions that sleep 

drop the interrupt priority level below the level at which the interrupt 
routine was entered 

call any function or routine that requires user context (that is, if it accesses 
or alters information associated with the running process) 

uiomove(D3DK), ureadc(D3DK), and uwritec(D3DK) cannot be used in 
an interrupt routine when the uio_segflg member of the uio(D4DK) 
structure is set to UIO_USERSPACE (indicating a transfer between user and 
kernel space). 

RETURN VALUE 

None. 

SEE ALSO 

biodone(D3DK), spl(D3D), SV_SI(asiAL(D3DK) 


Page 2 


3/91 



ioctl(D2DK) 


DDI/DKI 


ioctl(D2DK) 


An attempt should be made to keep the values for driver-specific I/O control 
commands distinct from others in the system. Each driver's I/O control com¬ 
mands are unique, but it is possible for user-level code to access a driver with an 
I/O control command that is intended for another driver, which can have serious 
results. 


A common method to assign I/O control command values that are less apt to be 
duplicated is to compose the commands from some component unique to the 
driver (such as a module name or ID), and a counter, as in: 


#define PREFIX 
#define COMMANDl 
ttdefine COMMAND2 
#define COMMANDS 


('h^«16rd'«8) 
(PREFIX ID 
(PREFIXI2) 
(PREFIX!3) 


RETURN VALUE 

The ioctl routine should return 0 on success, or the appropriate error number 
on failure. The system call will usually return 0 on success or -1 on failure. 
However, the driver can choose to have the system call return a different value 
on success by passing the value through the rvalp pointer. 

SEE ALSO 

open(D2DK), copyin(D3DK), copyout(D3DK), drv_priv(D3DK), ermos(D5DK) 
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SEE ALSO 

kvtoppid(D3DK), phystoppid(D3D) 
mmap(2) 
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ARGUMENTS 

devp 


[STREAMS] 

Pointer to the queue used to reference the read side of the driver. 

Pointer to a device number. For modules, devp always points to the 
device number associated with the driver at the end (tail) of the 
stream. 


oflag Open flags. Valid values are the same as those listed above. 

sflag STREAMS flag. Values are mutually exclusive and are given as fol¬ 

lows: 


CLONEOPEN Indicates a clone open (see below). If the driver supports 
cloning, it must assign and return a device number of an 
unused device by changing the value of the device 
number to which devp points. 

MODOPEN Indicates that an open routine is being called for a 
module, not a driver. This is useful in detecting 
configuration errors and in determining how the driver is 
being used, since STREAMS drivers can also be 
configured as STREAMS modules. 

0 Indicates a driver is being opened directly, without clon¬ 

ing. 

crp Pointer to the user credential structure. 

DESCRIPTION 

The driver's open routine is called to prepare a device for further access. It is 
called by the kernel during an open(2) or a nuDunt(2) of the device special file. 
For non-STREAMS drivers, it can also be called from another (layered) driver. 
The STREAMS module open routine is called by the kernel during an I_PUSH 
ioctl(2) or an autopush-style open [see autopush(lM)]. 

The open routine could perform any of the following general functions, depend¬ 
ing on the type of device and the service provided: 

enable interrupts 

allocate buffers or other resources needed to use the device 

lock an unsharable device 

notify the device of the open 

change the device number if this is a clone open 

The open routine should verify that the minor number component of devp is 
valid, that the type of access requested by otyp and oflag is appropriate for the 
device, and, if required, check permissions using the user credentials pointed to 
by crp [see drv_jpriv(D3DK)], 

Cloning is the process of the driver selecting an unused device for the user. It 
eliminates the need to poll many devices when looking for an unused one. Both 
STREAMS and Non-STREAMS drivers may implement cloning behavior by 
changing the device number pointed to by devp. A driver may designate certain 
minor devices as special clone entry points into the driver. When these are 
opened, the driver searches for an unused device and returns the new device 
number by changing the value of the device number to which devp points. Both 
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NAME 

print - display a driver message on the system console 

SYNOPSIS 

#include <sys/types.h> 
ttinclude <sys/ermo.h> 

int prefixpr±nt (dev_t dev, char *str ); 

ARGUMENTS 

dev Device number. 

str Pointer to a NULL-terminated character string describing the problem. 

DESCRIPTION 

The print routine is called indirectly by the kernel for the block device when the 
kernel has detected an exceptional condition (such as out of space) in the device. 
The driver should print the message on the console along with any driver-specific 
information. To display the message on the console, the driver should use the 
cinn_err(D3DK) function. 

NOTES 

This entry point is optional. 

The driver should not try to interpret the text string passed to it. 

The driver's print routine should not call any functions that sleep. 

RETURN VALUE 

Ignored. 

SEE ALSO 

cinn_err(D3DK) 
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} 

if (*mp->b_rptr & FLUSHR) { 

flushband(RD(q), FLUSHDATA, * (itp->b_rptr + 1)); 
qreply(q, rtp) ; 

} else { 

freemsg(mp); 

} 

} else { 

if (*mp->b_rptr & FLUSHW) { 
flushq(q, FLUSHDATA); 

*irp->b_rptr &= -FLUSHW; 

} 

if (*irp->b_rptr & FLUSHR) { 

flushq(RD(q), FLUSHDATA); 
qreply(q, itip) ; 

} else { 

freeiTisg(inp); 

} 

} 

The canonical flushing algorithm for module write put routines is as follows: 

queue_t *q; /* the write queue */ 

if (*inp->b_rptr & FLUSHBAND) { /* if module recognizes bands */ 
if (*np->b_rptr & FLUSHW) 

flushband(q, FLUSHDATA, *(np“>b_rptr + 1)); 
if (*iiip->b_rptr & FLUSHR) 

flushband(RD(q), FLUSHDATA, *(mp->b_rptr + 1)); 

} else { 

if (*i[p->b_rptr & FLUSHW) 
flushq(q, FLUSHDATA); 
if (*np->b_rptr & FLUSHR) 

flushq(RD(q), FLUSHDATA); 

} 

if (!SAMESTR(q)) { 

switch (*mp->b_rptr & FLUSHRW) { 
case FLUSHR: 

*mp->b_rptr = (*np->b_rptr & -FLUSHR) I FLUSHW; 
break; 

case FLUSHW: 

*mp->b_rptr = (*itp->b_rptr & -FLUSHW) I FLUSHR; 
break; 

} 

} 

put next (q, irp) ; 
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NAME 

read - read data from a device 

SYNOPSIS 

ttinclude <sys/types.h> 

#include <sys/ermo.h> 

#include <sys/uio.h> 
ttinclude <sys/cred.h> 

int prefixrea.6.(dev_t dev,\iio_t *uiop, cred_t *crp)} 

ARGUMENTS 

dev Device number. 

uiop Pointer to the uio(D4DK) structure that describes where the data is to 

be stored in user space. 

crp Pointer to the user credential structure for the I/O transaction. 

DESCRIPTION 

The driver read routine is called during the read(2) system call. The read rou¬ 
tine is responsible for transferring data from the device to the user data area. The 
pointer to the user credentials, crp, is available so the driver can check to see if 
the user can read privileged information, if the driver provides access to any. 
The uio structure provides the information necessary to determine how much 
data should be transferred. The uiomove(D3DK) function provides a convenient 
way to copy data using the uio structure. 

Block drivers that provide a character interface can use physiock(D3DK) to per¬ 
form the data transfer with the driver's strategy(D2DK) routine. 

NOTES 

This interface is optional. 

The read routine has user context and can sleep. 

RETURN VALUE 

The read routine should return 0 for success, or the appropriate error number. 

SEE ALSO 

strategy(D2DK), write(D2DK), drv_priv(D3DK), physiock(D3DK), 
uiQmove(D3DK), ureadc(D3DK), uio(D4DK), ermos(D5DK) 
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NAME 

srv - service queued messages 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/stream.h> 

#include <sys/stropts.h> 

int prefixrsrv {qaeuejt *q)} /* read side */ 

int prefixwsT^ {qaeue_t *q) i /* write side */ 

ARGUMENTS 

q Pointer to the queue. 

DESCRIPTION 

The service routine may be included in a STREAMS module or driver for a 
number of reasons. It provides greater control over the flow of messages in a 
stream by allowing the module or driver to reorder messages, defer the process¬ 
ing of some messages, or fragment and reassemble messages. Service routines 
also provide a way to recover from resource allocation failures. 

A message is first passed to a module's or driver's put(D2DK) routine, which 
may or may not process it. The put routine can place the message on the queue 
for processing by the service routine. 

Once a message has been enqueued, the STREAMS scheduler calls the service 
routine at some later time. Drivers and modules should not depend on the order 
in which service procedures are run. This is an implementation-dependent 
characteristic. In particular, applications should not rely on service procedures 
running before returning to user-level processing. 

Every STREAMS queue [see c3ueue(D4DK)] has limit values it uses to implement 
flow control. Tunable high and low water marks are checked to stop and restart 
the flow of message processing. Flow control limits apply only between two 
adjacent queues with service routines. Flow control occurs by service routines 
following certain rules before passing messages along. By convention, high prior¬ 
ity messages are not affected by flow control. 

STREAMS messages can be defined to have up to 256 different priorities to sup¬ 
port some networking protocol requirements for multiple bands of data flow. At 
a minimum, a stream must distinguish between normal (priority band zero) mes¬ 
sages and high priority messages (such as M_IOCACK). High priority messages are 
always placed at the head of the queue, after any other high priority messages 
already enqueued. Next are messages from all included priority bands, which are 
enqueued in decreasing order of priority. Each priority band has its own flow 
control limits. By convention, if a band is flow-controlled, all lower priority 
bands are also stopped. 

Once a service routine is called by the STREAMS scheduler it must process all 
messages on its queue, until either the queue is empty, the stream is flow- 
controlled, or an allocation error occurs. Typically, the service routine will switch 
on the message type, which is contained in np->b_datap->db_type, taking dif¬ 
ferent actions depending on the message type. The framework for the canonical 
service procedure algorithm is as follows: 
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put routines can interrupt and run concurrently with service routines. 

Only one copy of a queue's service routine will run at a time. 

Drivers and modules should not call service routines directly. qenable(D3DK) 
should be used to schedule service routines to run. 

Drivers should free any messages they do not recognize. 

Modules should pass on any messages they do not recognize. 

Drivers should fail any unrecognized M_IOCTL messages by converting them into 
M_I0CNAK messages and sending them upstream. 

Modules should pass on any unrecognized M_IOCTL messages. 

Service routines should never put high priority messages back on their queues. 

RETURN VALUE 

Ignored. 

SEE ALSO 

STREAMS Programmer's Guide 

put(D2DK), bcanputnext(D3DK), buf call(D3DK), canputnext(D3DK), 
getq(D3DK), pcansg(D3DK), putbq(D3DK), putnext(D3DK), putq(D3DK), 
qenable(D3DK), timeout(D3DK), datab(D4DK), msgb(D4DK), qinit(D4DK), 
queue(D4DK) 
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NAME 

strategy - perform block 1/O 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/buf.h> 

int prefixstrategy {struct buf *bp); 

ARGUMENTS 

bp Pointer to the buffer header. 

DESCRIPTION 

The strategy routine is called by the kernel to read and write blocks of data on 
the block device, strategy may also be called directly or indirectly (via a call to 
the kernel function physiock(D3DK)), to support the raw character interface of a 
block device from read(D2DK), write(D2DK) or ioctl(D2DK). The strategy 
routine's responsibility is to set up and initiate the data transfer. 

Generally, the first validation test performed by the strategy routine is to see if 
the I/O is within the bounds of the device. If the starting block number, given 
by bp->b_blkno, is less than 0 or greater than the number of blocks on the 
device, bioerror(D3DK) should be used to set the buffer error number to ENXIO, 
the buffer should be marked done by calling biodone(D3DK), and the driver 
should return. If bp">b_blkno is equal to the number of blocks on the device 
and the operation is a write, indicated by the absence of the B_READ flag in bp- 
>b_flags (! (bp“>b_flags & B_READ)), then the same action should be taken. 
However, if the operation is a read and bp“>b_blkno is equal to the number of 
blocks on the device, then the driver should set bp->b_resid equal to bp- 
>b_bcount, mark the buffer done by calling biodone, and return. This will cause 
the read to return 0. 

Once the I/O request has been validated, the strategy routine will queue the 
request. If there is not already a transfer under way, the I/O is started. Then the 
strategy routine returns. When the I/O is complete, the driver will call 
biodone to free the buffer and notify anyone who has called biowait(D3DK) to 
wait for the I/O to finish. 

There are two kinds of I/O requests passed to strategy routines: normal block 
I/O requests and paged-I/O requests. Normal block I/O requests are identified 
by the absence of the B_PAGEIO flag in bp->b_flags. Here, the starting virtual 
address of the data transfer will be found in bp->b_un.b_addr. Paged-I/O 
requests are identified by the presence of the B_PAGEI0 flag in bp->b_flags. 
These will not occur unless the driver has set the D_NOBRKUP flag [see 
devflag(DlD)]. The driver has several ways to perform a paged-I/O request. 

If the driver wants to use virtual addresses, it can call bp_inapin(D3DK) to get a 
virtually contiguous mapping for the pages. If the driver wants to use physical 
addresses, it can also use bp_inapin, but only transfer one page at a time. The 
physical address can be obtained by calling vtop(D3D) for each page in the vir¬ 
tual range. The size of a page can be determined by calling ptob(D3DK). How¬ 
ever, a more efficient way to use physical addresses is to use getnextpg(D3DK) 
and pptophys(D3D) for each page in the page list. 
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NAME 

write - write data to a device 

SYNOPSIS 

ttinclude <sys/types.h> 

#include <sys/ermo.h> 

#include <sys/uio.h> 

#include <sys/cred.h> 

int prefixwrite {dev_t dev,u±o_t *uiop, cred_t *crp); 

ARGUMENTS 

dev Device number. 

uiop Pointer to the uio(D4DK) structure that describes where the data is to 

be fetched from user space. 

crp Pointer to the user credential structure for the I/O transaction. 

DESCRIPTION 

The driver write routine is called during the write(2) system call. The write 
routine is responsible for transferring data from the user data area to the device. 
The pointer to the user credentials, crp, is available so the driver can check to see 
if the user can write privileged information, if the driver provides access to any. 
The uio structure provides the information necessary to determine how much 
data should be transferred. The uiQmove(D3DK) function provides a convenient 
way to copy data using the uio structure. 

Block drivers that provide a character interface can use physiock(D3DK) to per¬ 
form the data transfer with the driver's strategy(D2DK) routine. 

The write operation is intended to be synchronous from the caller's perspective. 
Minimally, the driver write routine should not return until the caller's buffer is 
no longer needed. For drivers that care about returning errors, the data should 
be committed to the device. For others, the data might only be copied to local 
staging buffers. Then the data will be committed to the device asynchronous to 
the user's request, losing the ability to return an error with the associated request. 

NOTES 

This interface is optional. 

The write routine has user context and can sleep. 

RETURN VALUE 

The write routine should return 0 for success, or the appropriate error number. 

SEE ALSO 

read(D2DK), strategy(D2DK), drv_priv(D3DK), physiock(D3DK), 
uioinove(D3DK), uwritec(D3DK), uio(D4DK), ermos(D5DK) 
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NAME 

adjmsg - trim bytes from a message 

SYNOPSIS 

#include <sys/stream.h> 

int adjmsg(inblk_t *mp, int len ); 

ARGUMENTS 

mp Pointer to the message to be trimmed. 

len The number of bytes to be removed. 

DESCRIPTION 

adjmsg removes bytes from a message. | len\ (the absolute value of len) specifies 
how many bytes are to be removed. If len is greater than 0, bytes are removed 
from the head of the message. If len is less than 0, bytes are removed from the 
tail, adjmsg fails if | len\ is greater than the number of bytes in mp. If len spans 
more than one message block in the message, the messages blocks must be the 
same type, or else adjmsg will fail. 

RETURN VALUE 

If the message can be trimmed successfully, 1 is returned. Otherwise, 0 is 
returned. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

If len is greater than the amount of data in a single message block, that message 
block is not freed. Rather, it is left linked in the message, and its read and write 
pointers are set equal to each other, indicating no data present in the block. 

SEE ALSO 

msgb(D4DK) 
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SEE ALSO 

Programmer's Guide: STREAMS 

bufcall(D3DK), esballoc(D3DK), esbbcall(D3DK), freeb(D3DK), msgb(D4DK) 

EXAMPLE 

Given a pointer to a queue (q) and an error number (err), the send_error routine 
sends an M_ERROR type message to the stream head. 

If a message cannot be allocated, 0 is returned, indicating an allocation failure 
(line 7). Otherwise, the message type is set to M_ERR.OR (line 8). Line 9 incre¬ 
ments the write pointer (bp“>b_wptr) by the size (one byte) of the data in the 
message. 

A message must be sent up the read side of the stream to arrive at the stream 
head. To determine whether q points to a read queue or a write queue, the q- 
>q_f lag member is tested to see if QREADR is set (line 10). If it is not set, q points 
to a write queue, and on line 11 the RD(D3DK) function is used to find the 
corresponding read queue. In line 12, the putnext(D3DK) function is used to 
send the message upstream. Then send_error returns 1 indicating success. 

1 send_error(q, err) 

2 queue_t *q; 

3 uchar_t err; 

4 { 

5 inblk_t *h£>} 

6 if ((bp = allocbd, BPRI_HI)) == NULL) 

7 retum(O); 

8 l:^->b_datap->db_type * M_ERROR; 

9 *l:p“>b_wptr++ = err; 

10 if (! (q->q:_flag & QREADR)) 

11 q = RD(q); 

12 putnext(q, bp); 

13 return (1); 

14 } 
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NAME 

bcanput - test for flow control in specified priority band 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/stream.h> 

int bcanput (queue_t *q, uchar_t pri) j 

ARGUMENTS 

q Pointer to the message queue, 

pn' Message priority. 

DESCRIPTION 

bcanput tests if there is room for a message in priority band prz of the queue 
pointed to by q. The queue must have a service procedure. 

If pri is 0, the bcanput call is equivalent to a call to canput. 

It is possible because of race conditions to test for room using bcanput and get 
an indication that there is room for a message, and then have the queue fill up 
before subsequently enqueuing the message, causing a violation of flow control. 
This is not a problem, since the violation of flow control in this case is bounded. 

RETURN VALUE 

bcanput returns 1 if a message of priority pri can be placed on the queue. 0 is 
returned if a message of priority pri cannot be enqueued because of flow control 
within the priority band. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

The driver is responsible for both testing a queue with bcanput and refraining 
from placing a message on the queue if bcanput fails. 

The caller cannot have the stream frozen [see freezestr(D3DK)] when calling 
this function. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

The q argument may not reference q_next (for example, an argument of q- 
>q_next is erroneous on a multiprocessor and is disallowed by the DDI/DKI). 
bcanputnext (q) is provided as a multiprocessor-safe equivalent to the common 
call bcanput (q->q_next), which is no longer allowed [see bcanputnext (D3DK)]. 

SEE ALSO 

bcanputnext (D3DK), canput (D3DK), canputnext(D3DK), putbq(D3DK), 
putnext (D3DK) 
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SEE ALSO 

bcanput(D3DK), canput(D3DK), canputnext(D3DK), putbq(D3DK), 
put next (D3DK) 
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1 #define RAMDNBLK 1000 /* number of blocks in the RAM disk */ 

2 #define RAMDBSIZ NBPSCTR /* t^es per block */ 

3 char raitidblks[RAMDNBLK] [RAMDBSIZ]; /* blocks forming RAM disk */ 

4 

5 if (bp->b_flags & B_READ) { 

6 /* 

7 * read request - copy data from RAM disk to system buffer 

8 */ 

9 bcopy(ramdblks[bp-->b_blkno], bp->b_un.b_addr, bp->b_bcount); 

10 

11 } else { 

12 /* 

13 * write request - copy data from system buffer to RAM disk 

14 */ 

15 bcopy(bp->b_un.b_addr, ramdblks[bp->bJblkno], bp->b_bcount); 

16 } 
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1 #define RAMDNBLK 1000 /* Number of blocks in RAM disk */ 

2 #define RAMDBSIZ 512 /* Number of bytes per block */ 

3 char ramdblks[RAMDNBLK] [RAMDBSIZ]; /* Array containing RAM disk */ 

4 ramdstrategyd^) 

5 register struct buf *bp; 

6 { 

7 register daddr_t blkno = bp“>b_blkno; 

8 if ((blkno < 0) II (blkno >= RAMDNBLK)) { 

9 if ((blkno == RAMDNBLK) && (bp->b_flags & B_READ)) { 

10 bp->b_resid = bp“>b_bcount; /* nothing read */ 

11 } else { 

12 bioerror(bp, ENXIO); 

13 } 

14 biodone(bp); 

15 return; 

16 } 
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NAME 

biowait - suspend processes pending completion of block I/O 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/buf.h> 

int biowait (buf_t *bp): 

ARGUMENTS 

bp Pointer to the buffer header structure. 

DESCRIPTION 

The biowait function suspends process execution during block I/O. Block 
drivers that have allocated their own buffers with geteblk(D3DK), 
getrbuf(D3DK), or ngeteblk(D3DK) can use biowait to suspend the current 
process execution while waiting for a read or write request to complete. 

Drivers using biowait must use biodone(D3DK) in their I/O completion 
handlers to signal biowait when the I/O transfer is complete. 

RETURN VALUE 

If an error occurred during the I/O transfer, the error number is returned. Oth¬ 
erwise, on success, 0 is returned. 

LEVEL 

Base Only. 

NOTES 

Can sleep. 

Driver-defined basic locks and read/write locks may not be held across calls to 
this function. 

Driver defined sleep locks may be held across calls to this function. 

SEE ALSO 

intr(D2D), strategy(D2DK), biodone(D3DK), geteblk(D3DK), 
getrbuf (D3DK), ngeteblk(D3DK), buf (D4DK) 
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NAME 

bp_niapout - deallocate virtual address space for buffer page list 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/buf.h> 

void bp_inapout (struct buf *bp): 

ARGUMENTS 

bp Pointer to the buffer header structure. 

DESCRIPTION 

This function deallocates the system virtual address space associated with a buffer 
header page list. The virtual address space must have been allocated by a previ¬ 
ous call to bp_inapin(D3DK). Drivers should not reference any virtual addresses 
in the mapped range after bp_inapout has been called. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

bp__mapin(D3DK), buf (D4DK) 
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NAME 

btop - convert size in bytes to size in pages (round down) 

SYNOPSIS 

ttinclude <sys/types.h> 

#include <sys/ddi.h> 

ulong_t btop(ulong_t numbytes): 

ARGUMENTS 

numbytes Size in bytes to convert to equivalent size in pages. 

DESCRIPTION 

btop returns the number of pages that are contained in the specified number of 
bytes, with downward rounding if the byte count is not a page multiple. 

For example, if the page size is 2048, then btop (4096) and btop (4097) both 
return 2, and btop (4095) returns 1. 

btop(O) returns 0. 

RETURN VALUE 

The return value is the number of pages. There are no invalid input values, and 
therefore no error return values. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

btopr(D3DK), ptob(D3DK) 
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NAME 

bufcall - call a function when a buffer becomes available 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/stream.h> 

toid_t bufcall(uint_t size, ±nt pri, void {*func) {), long arg); 

ARGUMENTS 

size Number of bytes in the buffer to be allocated (from the failed 
allocb(D3DK) request). 

pri Priority of the allocb allocation request (BPRl_LO, BPRI_MED, or BPRI_HI). 
func Function or driver routine to be called when a buffer becomes available. 
arg Argument to the function to be called when a buffer becomes available. 

DESCRIPTION 

bufcall serves as a timeout call of indeterminate length. When a buffer alloca¬ 
tion request fails, bufcall can be used to schedule the routine,/wnc, to be called 
with the argument, arg, when a buffer of at least size bytes becomes available. 

When func runs, all interrupts from STREAMS devices will be blocked on the pro¬ 
cessor on which it is running, func will have no user context and may not call 
any function that sleeps. 

RETURN VALUE 

If successful, bufcall returns a non-zero value that identifies the scheduling 
request. This non-zero identifier may be passed to unbufcall(D3DK) to cancel 
the request. If any failure occurs, bufcall returns 0. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

Even when func is called, allocb can still fail if another module or driver had 
allocated the memory before/wnc was able to call allocb. 

SEE ALSO 

allocb(D3DK), esballoc(D3DK), esbbcall(D3DK), itimeout(D3DK), 
unbuf cal 1 (D3DK) 

EXAMPLE 

The purpose of this service routine [see srv(D2DK)] is to add a header to all 
M_DATA messages. We assume only M_DATA messages are added to its queue. 
Service routines must process all messages on their queues before returning, or 
arrange to be rescheduled. 

While there are messages to be processed (line 21), we check to see if we can send 
the message on in the stream. If not, we put the message back on the queue (line 
23) and return. The STREAMS flow control mechanism will re-enable us later 
when messages can be sent. If canputnext(D3DK) succeeded, we try to allocate 
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34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 


inodp->m_type = TIMEOUT; 
} else { 

inodp->m_type = BUFCALL; 

} 

D]jn^K(inodp->m_lock, pi); 
return; 

} 

hp = (struct hdr *)l:^->b_wptr; 

hp->h_size = msgdsize (np) ; 

hp->h_version =1; 

bp->b_wptr += sizeof(struct hdr); 

bp->b_datap->db_type = M_PROTO; 

bp->b_cont = mp; 

putnext(q, bp); 


50 modcall(q) 

51 queue_t *q; 

52 { 

53 struct mod *modp; 

54 pl_t pi; 

55 modp = (struct mod *)q->q_ptr; 

56 pi = LOCK (modp->m_lock, plstr); 

57 modp->m_type = 0; 

58 UNLOCK (modp->m_lock, pi); 

59 qenable(q); 

60 } 
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NAME 

canput - test for room in a message queue 

SYNOPSIS 

#include <sys/stream.h> 
int canput(queue_t *q ); 

ARGUMENTS 

q Pointer to the message queue. 

DESCRIPTION 

canput tests if there is room for a message in the queue pointed to by q. The 
queue must have a service procedure. 

It is possible because of race conditions to test for room using canput and get an 
indication that there is room for a message, and then have the queue fill up 
before subsequently enqueuing the message, causing a violation of flow control. 
This is not a problem, since the violation of flow control in this case is bounded. 

RETURN VALUE 

canput returns 1 if a message can be placed on the queue. 0 is returned if a mes¬ 
sage cannot be enqueued because of flow control. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

The driver is responsible for both testing a queue with canput and refraining 
from placing a message on the queue if canput fails. 

The caller cannot have the stream frozen [see freezestr(D3DK)] when calling 
this function. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

The q argument may not reference qL_next (for example, an argument of q- 
>q_next is erroneous on a multiprocessor and is disallowed by the DDI/DKI). 
canputnext (q) is provided as a multiprocessor-safe equivalent to the common 
call canput (q->q_next), which is no longer allowed [see canputnext (D3DK)]. 

SEE ALSO 

bcanput(D3DK), bcanputnext(D3DK), canputnext (D3DK), putbq(D3DK), 
putnext (D3DK) 
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NAME 

clrbuf - erase the contents of a buffer 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/buf.h> 

void clrbuf (buf_t *bp)} 

ARGUMENTS 

bp Pointer to the buffer header structure. 

DESCRIPTION 

The clrbuf function zeros a buffer and sets the b_resid member of the 
buf(D4DK) structure to 0. Zeros are placed in the buffer starting at the address 
specified by b_un.b_addr for a length of b_bcount bytes. 

If the buffer has the B_PAGEIO flag set in the b_f lags field, then clrbuf should 
not be called until the proper virtual space has been allocated by a call to 
bp_inapin(D3DK). 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

bp_mapin(D3DK), buf (D4DK) 
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DESCRIPTION 

cinn__err displays a specified message on the console and/or stores it in the ker¬ 
nel buffer putbuf. cinn_err can also panic the system. 

At times, a driver may encounter error conditions requiring the attention of a sys¬ 
tem console monitor. These conditions may mean halting the system; however, 
this must be done with caution. Except during the debugging stage, or in the 
case of a serious, unrecoverable error, a driver should never stop the system. 

The cann_err function with the CE_CONT argument can be used by driver 
developers as a driver code debugging tool. However, using C5mn_err in this 
capacity can change system timing characteristics. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

If level is CE_PANIC, then driver defined basic locks, read/write locks, and sleep 
locks may not be held across calls to this function. For other levels, locks may be 
held. 

SEE ALSO 

print(D2DK) 

crash(lM) in the System Administrator's Reference Manual 
printf(3S) in the Programmer's Reference Manual 

EXAMPLE 

The caiin_err function can record tracing and debugging information only in the 
putbuf buffer (lines 12 and 13) or display problems with a device only on the 
system console (lines 17 and 18). 

1 struct device { /* device registers layout */ 

2 int status; /* device status word */ 

3 }; 

4 extern struct device xx_dev[]; /* physical device registers */ 

5 extern int xx_cnt; /* number of physical devices */ 

6 int 

7 xxopen(dev_t *devp, int flag, int otyp, cred_t *crp) 

8 { 

9 register struct device *dp; 

10 dp = xx_dev[getminor(*devp) ]; /* get dev registers */ 

11 #ifdef DEBUG /* in debugging mode, log function call */ 

12 cmn_err(CE_NOTE, "Ixxopen fimction call, dev = OxSax", *devp); 

13 cran_err(CE_CONT, "I flag = 0x?8x", flag); 

14 #endif 

15 /* display device power failiire on system console */ 
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NAME 

copyb - copy a message block 

SYNOPSIS 

#include <sys/stream.h> 
inblk_t *copyb(i[iblk_t *bp): 

ARGUMENTS 

bp Pointer to the message block from which data are copied. 

DESCRIPTION 

copyb allocates a new message block, and copies into it the data from the block 
pointed to by bp. The new block will be at least as large as the block being 
copied. The b_rptr and b_wptr members of the message block pointed to by bp 
are used to determine how many bytes to copy. 

RETURN VALUE 

If successful, copyb returns a pointer to the newly allocated message block con¬ 
taining the copied data. Otherwise, it returns a NULL pointer. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

allocb(D3DK), copymsg(D3DK), msgb(D4DK) 

EXAMPLE 

This example illustrates how copyb can be used during message retransmission. 
If there are no messages to retransmit, we return (line 21). Otherwise, we lock 
the retransmission list (line 23). For each retransmission record in the list, we test 
to see if either the message has already been retransmitted, or if the downstream 
queue is full (by calling canputnext(D3DK) on line 26). If either is true, we skip 
the current retransmission record and continue searching the list. Otherwise, we 
use copyb(D3DK) to copy a header message block (line 30), and dupmsg(D3DK) 
to duplicate the data to be retransmitted (line 32). 

If either operation fails, we clean up and break out of the loop. Otherwise, we 
update the new header block with the correct destination address (line 37), link 
the message to be retransmitted to it (line 38), mark the retransmission record as 
having sent the message (line 39), unlock the retransmission list (line 40), and 
send the message downstream (line 41). Then we go back and lock the list again 
and start searching for more messages to retransmit. 

This continues until we are either at the end of the retransmission list, or unable 
to send a message because of allocation failure. With the list still locked, we clear 
all the flags for sent messages (lines 44 and 45). Finally, we unlock the list lock 
and reschedule a timeout at the next valid interval (line 47) and return. Since 
we are using itimeout(D3DK), retransmit will run at the specified processor 
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NAME 

copyin - copy data from a user buffer to a driver buffer 

SYNOPSIS 

#include <sys/types.h> 

int copyin(caddr_t userbufr ca.6.dr_t driverbuf, s±ze_t count); 

ARGUMENTS 

userbuf User source address from which copy is made. 
driverbuf Driver destination address to which copy is made. 
count Number of bytes to copy. 

DESCRIPTION 

copyin copies count bytes of data from the user virtual address specified by user¬ 
buf to the kernel virtual address specified by driverbuf. The driver must ensure 
that adequate space is allocated for the destination address. 

copyin chooses the best algorithm based on address alignment and number of 
bytes to copy. Although the source and destination addresses are not required to 
be word aligned, word aligned addresses may result in a more efficient copy. 

RETURN VALUE 

If the copy is successful, 0 is returned. Otherwise, -1 is returned to indicate that 
the specified user address range is not valid. 

LEVEL 

Base Only. 

NOTES 

May sleep. 

Drivers usually convert a return value of -1 into an EFAULT error. 

Driver-defined basic locks and read/write locks may not be held across calls to 
this function. 

Driver-defined sleep locks may be held across calls to this function. 

When holding sleep locks across calls to this function, drivers must be careful to 
avoid creating a deadlock. During the data transfer, page fault resolution might 
result in another I/O to the same device. For example, this could occur if the 
driver controls the disk drive used as the swap device. 

The driver destination buffer must be completely within the kernel address space, 
or the system can panic. 

SEE ALSO 

bcopy(D3DK), copyout(D3DK), uiamove(D3DK), ureadc(D3DK), u'writec(D3DK) 

EXAMPLE 

A driver ioctl(D2DK) routine (line 5) can be used to get or set device attributes 
or registers. If the specified command is XX_SETREGS (line 9), the driver copies 
user data to the device registers (line 11). If the user address is invalid, an error 
code is returned. 
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NAME 

copymsg - copy a message 

SYNOPSIS 

#include <sys/stream.h> 
mblk_t *copymsg(inblk_t *nip); 

ARGUMENTS 

mp Pointer to the message to be copied. 

DESCRIPTION 

copymsg forms a new message by allocating new message blocks, copies the con¬ 
tents of the message referred to by mp (using the copyb(D3DK) function), and 
returns a pointer to the new message. 

RETURN VALUE 

If successful, copymsg returns a pointer to the new message. Otherwise, it 
returns a NULL pointer. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

allocb(D3DK), copyb(D3DK), msgb(D4DK) 

EXAMPLE 

The routine Ictouc converts all the lower case ASCII characters in the message to 
upper case. If the reference count is greater than one (line 8), then the message is 
shared, and must be copied before changing the contents of the data buffer. If 
the call to copymsg fails (line 9), we return NULL (line 10). Otherwise, we free the 
original message (line 11). If the reference count was equal to one, the message 
can be modified. For each character (line 16) in each message block (line 15), if it 
is a lower case letter, we convert it to an upper case letter (line 18). When done, 
we return a pointer to the converted message (line 21). 

1 mblk_t *lctouc(n 5 )) 

2 inblk_t *np; 

3 { 

4 niblk_t *amp; 

5 niblk_t *tnp; 

6 uchar_t *cp; 

7 

8 if (iip->b_datap->db_ref >1) { 

9 if ((carp = copymsg (mp)) == NULL) 

10 return(NULL); 

11 freemsg(mp); 

12 } else { 

13 cmp = mp; 

14 } 
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NAME 

copyout - copy data from a driver buffer to a user buffer 

SYNOPSIS 

#include <sys/types.h> 

int copyout (caddr_t driverbuf, ca.ddr_t userbuf, s±ze_t count); 

ARGUMENTS 

driverbuf Driver source address from which copy is made. 
userbuf User destination address to which copy is made. 
count Number of bytes to copy. 

DESCRIPTION 

copyout copies count bytes of data from the kernel virtual address specified by 
driverbuf to the user virtual address specified by userbuf 

copyout chooses the best algorithm based on address alignment and number of 
bytes to copy. Although the source and destination addresses are not required to 
be word aligned, word aligned addresses may result in a more efficient copy. 

RETURN VALUE 

If the copy is successful, 0 is returned. Otherwise, -1 is returned to indicate that 
the specified user address range is not valid. 

LEVEL 

Base Only. 

NOTES 

May sleep. 

Drivers usually convert a return value of -1 into an EFAULT error. 

Driver-defined basic locks and read/write locks may not be held across calls to 
this function. 

Driver-defined sleep locks may be held across calls to this function. 

When holding sleep locks across calls to this function, drivers must be careful to 
avoid creating a deadlock. During the data transfer, page fault resolution might 
result in another I/O to the same device. For example, this could occur if the 
driver controls the disk drive used as the swap device. 

The driver source buffer must be completely within the kernel address space, or 
the system can panic. 

SEE ALSO 

bcopy(D3DK), copyin(D3DK), uiomove(D3DK), ureadc(D3DK), uwritec(D3DK) 

EXAMPLE 

A driver ioctl(D2DK) routine (line 5) can be used to get or set device attributes 
or registers. If the specified command is xx_GETREGS (line 9), the driver copies 
the current device register values to a user data area (line 11). If the user address 
is invalid, an error code is returned. 
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NAME 

datamsg - test whether a message is a data message 

SYNOPSIS 

ttinclude <sys/types.h> 

#include <sys/stream.h> 
ttinclude <sys/ddi.h> 

int datamsg(uchar_t type): 

ARGUMENTS 

type The type of message to be tested. The db_type field of the datab 

structure contains the message type. This field may be accessed 
through the message block using mp->b_datap->db_type. 

DESCRIPTION 

The datamsg function tests the type of message to determine if it is a data mes¬ 
sage type (M_DATA, M_DELAY, M_PROTO, or M_PCPROTO). 

RETURN VALUE 

datamsg returns 1 if the message is a data message and 0 if the message is any 
other type. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

allocb(D3DK), datab(D4DK), msgb(D4DK), messages(D5DK) 

EXAMPLE 

The put(D2DK) routine enqueues all data messages for handling by the 
srv(D2DK) (service) routine. All non-data messages are handled in the put rou¬ 
tine. 

1 xxxput(q, np) 

2 queue_t *q; 

3 mblk_t *np; 

4 { 

5 if (datamsg (np->b_datap->db_type)) { 

6 putq(q, np); 

7 return; 

8 } 

9 switch (np->b_datap->db_t 3 ,pe) { 

10 case M_FLUSH: 

11 } 

12 } 
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NAME 

dma_pageio - break up an 1/O request into manageable units 

SYNOPSIS 

#include <sys/buf.h> 

void dina_pageio(void strut) {), buf_t *bp); 

ARGUMENTS 

strut Address of the strategy(D2DK) routine to call to complete the I/O 
transfer. 

bp Pointer to the buffer header structure. 

DESCRIPTION 

dina_pageio breaks up a data transfer request from physiock(D3DK) into units 
of contiguous memory. This function enhances the capabilities of the direct 
memory access controller (DMAC). 

RETURN VALUE 

None. 

LEVEL 

Base Only. 

NOTES 

Can sleep. 

Driver-defined basic locks and read/write locks may not be held across calls to 
this function. 

Driver defined sleep locks may be held across calls to this function. 

When the transfer completes, any allocated buffers are freed. 

The interrupt priority level is not maintained across calls to dma__pageio. 

SEE ALSO 

read(D2DK), strategy(D2DK), write(D2DK), physiock(D3DK), buf (D4DK) 

EXAMPLE 

The following example shows how dma_pageio is used when reading or writing 
disk data. The driver's read(D2DK) and write(D2DK) entry points use phy- 
siock to check the validity of the I/O and perform the data transfer. The 
strategy(D2DK) routine passed to physiock just calls <aina_pageio to perform 
the data transfer one page at a time. 
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NAME 

dr y g etparm - retrieve kernel state information 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ddi.h> 

int drv_getparm(ulong_t parm, ulong_t *value_p ); 

ARGUMENTS 

parm The kernel parameter to be obtained. Possible values are: 

LBOLT Read the number of clock ticks since the last system 
reboot. The difference between the values returned from 
successive calls to retrieve this parameter provides an 
indication of the elapsed time between the calls in units 
of clock ticks. The length of a clock tick can vary across 
different implementations, and therefore drivers should 
not include any hard-coded assumptions about the length 
of a tick. The drv_hztousec(D3DK) and 
drv_usectohz(D3DK) functions can be used, as neces¬ 
sary, to convert between clock ticks and microseconds 
(implementation independent units). 

UPROCP Retrieve a pointer to the process structure for the current 
process. The value returned in "^valuejp is of type 
(proc_t *) and the only valid use of the value is as an 
argument to vtop(D3D). Since this value is associated 
with the current process, the caller must have process 
context (that is, must be at base level) when attempting 
to retrieve this value. Also, this value should only be 
used in the context of the process in which it was 
retrieved. 

UCRED Retrieve a pointer to the credential structure describing 
the current user credentials for the current process. The 
value returned in "^valuej) is of type (cred_t *) and the 
only valid use of the value is as an argument to 
drv_priv(D3DK). Since this value is associated with the 
current process, the caller must have process context (i.e. 
must be at base level) when attempting to retrieve this 
value. Also, this value should only be used in the con¬ 
text of the process in which it was retrieved. 

TIME Read the time in seconds. This is the same time value 
that is returned by the time(2) system call. The value is 
defined as the time in seconds since 00:00:00 GMT, 
January 1 , 1970. This definition presupposes that the 
administrator has set the correct system date and time. 

valuej) A pointer to the data space into which the value of the parameter is to 
be copied. 
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NAME 

drv_hztousec - convert clock ticks to microseconds 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ddi.h> 

clock_t drv_hztousec(clock_t ticks): 

ARGUMENTS 

ticks The number of clock ticks to convert to equivalent microseconds. 

DESCRIPTION 

drv_hztousec converts the length of time expressed by ticks, which is in units of 
clock ticks, into units of microseconds. 

Several functions either take time values expressed in clock ticks as arguments 
[itimeout(D3DK), delay(D3DK)] or return time values expressed in clock ticks 
[drv_getparm(D3DK)]. The length of a clock tick can vary across different imple¬ 
mentations, and therefore drivers should not include any hard-coded assumptions 
about the length of a tick. drv_hztousec and the complementary function 
drv_usectohz(D3DK) can be used, as necessary, to convert between clock ticks 
and microseconds. 

RETURN VALUE 

The number of microseconds equivalent to the ticks argument. No error value is 
returned. If the microsecond equivalent to ticks is too large to be represented as a 
clock_t, then the maximum clock_t value will be returned. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

The time value returned by drv_getparm with an LBOLT argument will fre¬ 
quently be too large to represent in microseconds as a clock_t. When using 
drv qetparm together with drv_hztousec to time operations, drivers can help 
avoid overflow by converting the difference between return values from succes¬ 
sive calls to dr v q etparm instead of trying to convert the return values them¬ 
selves. 

SEE ALSO 

delay(D3DK), drv_getpann(D3DK), drv_usectohz(D3DK), dtimeout(D3D), 
i t imeout (D3DK) 
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NAME 

drv_setpann - set kernel state information 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ddi.h> 

int drv_setparm(ulong_t parm, ulong_t value ); 

ARGUMENTS 

parm The kernel parameter to be updated. Possible values are: 

SYSCANC Add value to the count of the number of characters received 
from a terminal device after the characters have been processed 
to remove special characters such as break or backspace. 

SYSMINT Add value to the count of the number of modem interrupts 
received. 

SYSOUTC Add value to the coimt of the number of characters output to a 
terminal device. 

SYSRAWC Add value to the count of the number of characters received 
from a terminal device, before canonical processing has 
occurred. 

SYSRINT Add value to the count of the number of interrupts generated 
by data ready to be received from a terminal device. 

SYSXINT Add value to the count of the number of interrupts generated 
by data ready to be transmitted to a terminal device. 

value The value to be added to the parameter. 

DESCRIPTION 

drv_setpann verifies that parm corresponds to a kernel parameter that may be 
modified. If the value of parm corresponds to a parameter that may not be 
modified, -1 is returned. Otherwise, the parameter is incremented by value. 

No checking is performed to determine the validity of value. It is the driver's 
responsibility to guarantee the correctness of value. 

RETURN VALUE 

If the function is successful, 0 is returned. Otherwise, -1 is returned to indicate 
that parm specified an invalid parameter. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

drv_getparm(D3DK) 
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NAME 

drv_usecwait - busy-wait for specified interval 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ddi.h> 


void drv_usecwait (clock_t microsecs) p 

ARGUMENTS 

microsecs The number of microseconds to busy-wait. 

DESCRIPTION 

drv_usecwait causes the caller to busy-wait for at least the number of 
microseconds specified by microsecs. The amount of time spent busy-waiting may 
be greater than the time specified by microsecs but will not be less. 
drv_usecwait should only be used to wait for short periods of time (less than a 
clock tick) or when it is necessary to wait without sleeping (for example, at inter¬ 
rupt level). When the desired delay is at least as long as clock tick and it is possi¬ 
ble to sleep, the delay(D3DK) function should be used instead since it will not 
waste processor time busy-waiting as drv_usecwait does. 

Because excessive busy-waiting is wasteful the driver should only make calls to 
drv_usecwait as needed, and only for as much time as needed. drv_usecwait 
does not raise the interrupt priority level; if the driver wishes to block interrupts 
for the duration of the wait, it is the driver's responsibility to set the priority level 
before the call and restore it to its original value afterward. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

Busy-waiting can increase the preemption latency experienced by high priority 
processes. Since short and bounded preemption latency can be critical in a real 
time environment, drivers intended for use in such an environment should not 
use this interface or should limit the length of the wait to an appropriately short 
length of time. 

SEE ALSO 

dielay(D3DK), drv_hztousec(D3DK), drv_usectohz(D3DK), itimeout(D3DK), 
imt imeou t (D3DK) 
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Otherwise, fn is deferred until some time in the near future. 

If dtimeout is called holding a lock that is contended for by fn, the caller must 
hold the lock at a processor level greater than the base processor level. 

A ticks argument of 0 has the same effect as a ticks argument of 1. Both will 
result in an approximate wait of between 0 and 1 tick (possibly longer). 

SEE ALSO 

itimeout(D3DK), L0CK__ALL0C(D3DK), untimeout(D3DK) 
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Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

copyb(D3DK), dupmsg(D3DK), datab(D4DK), msgb(D4DK) 
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NAME 

enableok - allow a queue to be serviced 

SYNOPSIS 

#include <sys/stream.h> 

#include <sys/ddi.h> 

void enableok (queue_t *q); 

ARGUMENTS 

q Pointer to the queue. 

DESCRIPTION 

The enableok function allows the service routine of the queue pointed to by q to 
be rescheduled for service. It cancels the effect of a previous use of the 
noenable(D3DK) function on q. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

The caller cannot have the stream frozen [see freezestr(D3DK)] when calling 
this function. 

SEE ALSO 

srv(D2DK), noenable(D3DK), qenable(D3DK), qaeue(D4DK) 

EXAMPLE 

The qrestart routine uses two STREAMS functions to re-enable a queue that has 
been disabled. The enableok function removes the restriction that prevented the 
queue from being scheduled when a message was enqueued. Then, if there are 
messages on the queue, it is scheduled by calling qenable(D3DK). 

1 void 

2 qrestart(q) 

3 register queue_t *q; 

4 { 

5 enableok (q); 

6 if (q->q_first) 

7 qenable(q); 

8 } 
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NAME 

esbbcall - call a function when an externally-supplied buffer can be allocated 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/stream.h> 

toid_t esbbcall (int pn, void {*func) {), long arg) j 

ARGUMENTS 

pri Priority of the esballoc(D3DK) allocation request (BPRI_IjO, 

BPRI_MED, or BPRI_HI.) 

func Function to be called when a buffer becomes available. 

arg Argument to the function to be called when a buffer becomes avail¬ 

able. 

DESCRIPTION 

esbbcall, like bufcall(D3DK), serves as a timeout call of indeterminate length. 
If esballoc(D3DK) is unable to allocate a message block header and a data block 
header to go with its externally supplied data buffer, esbbcall can be used to 
schedule the routine func, to be called with the argument arg when memory 
becomes available. 

When func runs, all interrupts from STREAMS devices will be blocked on the pro¬ 
cessor on which it is running, func will have no user context and may not call 
any function that sleeps. 

RETURN VALUE 

If successful, esbbcall returns a non-zero value that identifies the scheduling 
request. This non-zero identifier may be passed to uiibufcall(D3DK) to cancel 
the request. If any failure occurs, esbbcall returns 0. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

Even when func is called, esballoc can still fail if another module or driver had 
allocated the memory before func was able to call allocb. 

SEE ALSO 

allocb(D3DK), bufcall(D3DK), esballoc(D3DK), itimeout(D3DK), 
unbuf cal 1 (D3DK) 
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NAME 

f lushband - flush messages in a specified priority band 

SYNOPSIS 

ttinclude <sys/types.h> 

#include <sys/stream.h> 

void f lushband (queue_t uchar_t pn, int flag ); 

ARGUMENTS 

q Pointer to the queue. 

pri Priority band of messages to be flushed. 

flag Determines messages to flush. Valid flag values are: 

FLUSHDATA Flush only data messages (types M_DATA, M_delay, 
M_PROTO, and M_PCPROTO). 

FLUSHALL Flush all messages. 

DESCRIPTION 

The f lushband function flushes messages associated with the priority band 
specified by pri. If pri is 0, only normal and high priority messages are flushed. 
(Otherwise, messages are flushed from the band pri according to the value of flag. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

The caller cannot have the stream frozen [see freezestr(D3DK)] when calling 
this function. 

SEE ALSO 

put(D2DK), f lushq(D3DK), queue(D4DK) 

EXAMPLE 

See put(D2DK) for an example of f lushband. 
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NAME 

f reeb - free a message block 

SYNOPSIS 

#include <sys/streain.h> 
void freeb(mblk_t *bp) s 

ARGUMENTS 

bp Pointer to the message block to be deallocated. 

DESCRIPTION 

f reeb deallocates a message block. If the reference count of the db_ref member 
of the datab(D4DK) structure is greater than 1, freeb decrements the count and 
returns. Otherwise, if db_ref equals 1, it deallocates the message block and the 
corresponding data block and buffer. 

If the data buffer to be freed was allocated with esballoc(D3DK), the driver is 
notified that the attached data buffer needs to be freed by calling the free-routine 
[see free_rtn(D4DK)] associated with the data buffer. Once this is accom¬ 
plished, freeb releases the STREAMS resources associated with the buffer. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

allocb(D3DK), dupb(D3DK), esballoc(D3DK), datab(D4DK), free_rtn(D4DK), 
msgb(D4DK) 

EXAMPLE 

See copyb(D3DK) for an example of freeb. 
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NAME 

freerbuf - free a raw buffer header 

SYNOPSIS 

#include <sys/buf.h> 
ttinclude <sys/ddi.h> 

void freerbuf(buf_t *bp) ; 

ARGUMENTS 

bp Pointer to a previously allocated buffer header structure. 

DESCRIPTION 

freerbuf frees a raw buffer header previously allocated by getrbuf(D3DK). It 
may not be used on a buffer header obtained through any other interface. It is 
typically called from a driver's iodone handler, specified in the b_iodone field of 
the buf (D4DK) structure. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

biodone(D3DK), biowait(D3DK), getrbuf(D3DK), buf(D4DK) 
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NAME 

geteblk - get an empty buffer 

SYNOPSIS 

tinclude <sys/types.h> 

#include <sys/buf.h> 

buf_t *geteblk(); 

DESCRIPTION 

geteblk retrieves a buffer [see buf(D4DK)] from the buffer cache and returns a 
pointer to the buffer header. If a buffer is not available, geteblk sleeps until one 
is available. 

When the driver strategy(D2DK) routine receives a buffer header from the ker¬ 
nel, all the necessary members are already initialized. However, when a driver 
allocates buffers for its own use, it must set up some of the members before cal¬ 
ling its strategy routine. 

The following list describes the state of these members when the buffer header is 
received from geteblk: 

b_flags is set to indicate the transfer is from the user's buffer to the ker¬ 

nel. The driver must set the B_READ flag if the transfer is from the 
kernel to the user's buffer. 

b_edev is set to NODEV and must be initialized by the driver. 

b_bcount is set to 1024. 

b_un.b_addr is set to the buffer's virtual address. 

b_blkno is not initialized by geteblk, and must be initialized by the driver 

Typically, block drivers do not allocate buffers. The buffer is allocated by the 
kernel, and the associated buffer header is used as an argument to the driver 
strategy routine. However, to implement some special features, such as 
ioctl(D2DK) commands that perform I/O, the driver may need its own buffer 
space. The driver can get the buffer space from the system by using geteblk or 
ngeteblk(D3DK). Or the driver can choose to use its own memory for the buffer 
and only allocate a buffer header with getrbuf (D3DK). 

RETURN VALUE 

A pointer to the buffer header structure is returned. 

LEVEL 

Base Only. 

NOTES 

Can sleep. 

Driver-defined basic locks and read/write locks may not be held across calls to 
this function. 

Driver-defined sleep locks may be held across calls to this function. 
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NAME 

getemajor - get external major device number 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ddi.h> 

ma j or_t get ema j or (dev_t dev ); 

ARGUMENTS 

dev External device number. 

DESCRIPTION 

getemajor returns the external major number given a device number, dev. Exter¬ 
nal major numbers are visible to the user. Internal major numbers are only visi¬ 
ble in the kernel. Since the range of major numbers may be large and sparsely 
populated, the kernel keeps a mapping between external and internal major 
numbers to save space. 

All driver entry points are passed device numbers using external major numbers. 

Usually, a driver with more than one external major number will have only one 
internal major number. However, some system implementations map one-to-one 
between external and internal major numbers. Here, the internal major number is 
the same as the external major number and the driver may have more than one 
internal major number. 

RETURN VALUE 

The external major number. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

etoimajor(D3DK), geteminor(D3DK), getinajor(D3DK), getminor(D3DK), 
inakedevice(D3DK) 
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NAME 

geterror - retrieve error number from a buffer header 

SYNOPSIS 

#include <sys/buf.h> 

int geterror(struct buf *bp): 

ARGUMENTS 

bp Pointer to the buffer header. 

DESCRIPTION 

geterror is called to retrieve the error number from the error field of a buffer 
header (buf(D4DK) structure). 

RETURN VALUE 

An error number indicating the error condition of the 1/O request is returned. If 
the I/O request completed successfully, 0 is returned. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

buf (D4DK), ermos(D5DK) 
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NAME 

getminor - get internal minor device number 

SYNOPSIS 

#include <sys/types.h> 
ttinclude <sys/ddi.h> 

minor_t getminor (dev_t dev ); 

ARGUMENTS 

dev Device number. 

DESCRIPTION 

The getminor function extracts the internal minor number from a device number. 
See getemajor(D3DK) for an explanation of external and internal major numbers. 

RETURN VALUE 

The internal minor number. 

LEVEL 

Base or Interrupt. 

NOTES 

No validity checking is performed. If dev is invalid, an invalid number is 
returned. 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

etoimajor(D3DK), getemajor(D3DK), geteminor(D3DK), getmajor(D3DK), 
makedevice(D3DK) 
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NAME 

getq - get the next message from a queue 

SYNOPSIS 

#include <sys/stream.h> 
mblk_t *getq(queue_t *q); 

ARGUMENTS 

q Pointer to the queue from which the message is to be retrieved. 

DESCRIPTION 

getq is used by service [see srv(D2DK)] routines to retrieve queued messages. It 
gets the next available message from the top of the queue pointed to by q. getq 
handles flow control, restarting I/O that was blocked as needed. 

RETURN VALUE 

If there is a message to retrieve, getq returns a pointer to it. If no message is 
queued, getq returns a NULL pointer. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

The caller cannot have the stream frozen [see freezestr(D3DK)] when calling 
this function. 

SEE ALSO 

srv(D2DK), bcanput(D3DK), canput(D3DK), putbq(D3DK), putq(D3DK), 
qenable(D3DK), nnvq(D3DK) 

EXAMPLE 

See srv(D2DK) for an example of getq. 
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LEVEL 

Base only if flag is set to KM_SLEEP. Base or interrupt if flag is set to KM_NOSLEEP. 

NOTES 

May sleep if flag is set to KM_SLEEP. 

Driver-defined basic locks and read/write locks may be held across calls to this 
function if flag is KM_NOSLEEP, but may not be held if flag is KM_SLEEP. 

Driver-defined sleep locks may be held across calls to this function regardless of 
the value of flag. 

SEE ALSO 

biodone(D3DK), biowait(D3DK), freerbuf(D3DK), buf(D4DK) 
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NAME 

ini - read a 32 bit word from a 32 bit I/O port 

SYNOPSIS 

#include <sys/types.h> 
ulong_t ini (int port ); 

ARGUMENTS 

port A valid 32 bit 1/O port. 

DESCRIPTION 

This function provides a C language interface to the machine instruction that 
reads a 32 bit word from a 32 bit I/O port using the I/O address space, instead 
of the memory address space. 

RETURN VALUE 

Returns the value of the 32 bit word read from the I/O port. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

This function may not be meaningful on all implementations because some imple¬ 
mentations may not support I/O-mapped 1/O. 

SEE ALSO 

Programmer's Reference Manual 
Integrated Software Development Guide 

irLb(D3D), inw(D3D), outb(D3D), outl(D3D), outw(D3D), repinsb(D3D), 
repinsd(D3D), repinsw(D3D), repoutsb(D3D), repoutsd(D3D), repoutsw(D3D) 
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message (line 13), we free the entire message using freemsg(D3DK). Otherwise, 
for every M_PROTO message block in the message, we strip the M_PROTO block off 
using xmlinkb(D3DK) (line 17) and free the message block using freeb(D3DK). 
When the header has been stripped, the data portion of the message is inserted 
back into the queue where it was originally found (line 21). Finally, when we are 
done searching the queue, we unfreeze the stream (line 26). 

1 void 

2 striproto(q) 

3 queue_t *q; 

4 { 

5 register inblk_t *eirp, *nnp, * 115 ); 

6 pl_t pi; 


7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 } 


pi = freezestr(q); 
inp = q->q_first; 
while (itp) { 

emp = mp->b_next; 

if (irp->b_datap->db_type == M_PROTO) { 
rmvq(q, mp); 

if (insgdsize(np) == 0 ) { 
freeinsg(irp); 

} else { 

while (inp->b_datap->db_type == M_PROTO) { 
rmp =: tinlinkb(mp); 
freeb(irp); 
mp = nmp; 

} 

insq(q, errp, mp); 

} 

} 

Bnp = emp; 

} 

unfreezestr(q, pi); 
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NAME 

itimeout - execute a function after a specified length of time 

SYNOPSIS 

#include <sys/types.h> 

toid_t itimeout (void {*fn) {), void *arg, long ticks, i>l_t pi); 

ARGUMENTS 

fn Function to execute when the time increment expires. 

arg Argument to the function. 

ticks Number of clock ticks to wait before the function is called. 

pi The interrupt priority level at which the function will be called, pi 

must specify a priority level greater than or equal to pltimeout; thus, 
plbase cannot be used. See L0CK_ALL0C(D3DK) for a list of values for 
pi. 

DESCRIPTION 

itimeout causes the function specified by^ to be called after the time interval 
specified by ticks, at the interrupt priority level specified by pi. arg will be passed 
as the only argument to function fn. The itimeout call returns immediately 
without waiting for the specified function to execute. 

The length of time before the function is called is not guaranteed to be exactly 
equal to the requested time, but will be at least ticks-1 clock ticks in length. The 
function specified by^ must neither sleep nor reference process context. 

RETURN VALUE 

If the function specified by fn is successfully scheduled, itimeout returns a non¬ 
zero identifier that can be passed to untimeout to cancel the request. If the func¬ 
tion could not be scheduled, itimeout returns a value of 0. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

Drivers should be careful to cancel any pending timeout functions that access 
data structures before these structures are de-initialized or deallocated. 

After the time interval has expired, fn only runs if the processor is at base level. 
Otherwise, fn is deferred until some time in the near future. 

If itimeout is called holding a lock that is contended for by fn, the caller must 
hold the lock at a processor level greater than the base processor level. 

A ticks argument of 0 has the same effect as a ticks argument of 1. Both will 
result in an approximate wait of between 0 and 1 tick (possibly longer). 
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NAME 

itoemajor - convert internal to external major device number 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ddi.h> 

inajor_t itoemajor (inajor_t imaj, major_t prevemaj) p 

ARGUMENTS 

imaj Internal major number. 

prevemaj Most recently obtained external major number (or NODEV, if this is the 
first time the function has been called). 

DESCRIPTION 

itoemajor converts the internal major number to the external major number. 
The external-tO“internal major number mapping can be many-to-one, and so any 
internal major number may correspond to more than one external major number. 
By repeatedly invoking this fimction and passing the most recent external major 
number obtained, the driver can obtain all possible external major number values. 
See getemajor(D3DK) for an explanation of external and internal major numbers. 

RETURN VALUE 

External major number, or NODEV, if all have been searched. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

etoimajor(D3DK), getemajor(D3DK), geteminor(D3DK), getmajor(D3DK), 
getminor(D3DK), makedevice(D3DK) 
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NAME 

kmem_free - free previously allocated kernel memory 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/kmem.h> 

void kmem_free(void *addr, size_t size)} 

ARGUMENTS 

addr Address of the allocated memory to be returned, addr must specify 
the same address that was returned by the corresponding call to 
kmem_alloc(D3DK) or kmeni_zalloc(D3DK) which allocated the 
memory. 

size Number of bytes to free. The size parameter must specify the same 

number of bytes as was allocated by the corresponding call to 
kmem_alloc or kmem_zalloc. 

DESCRIPTION 

kmem_free returns size bytes of previously allocated kernel memory. The addr 
and size arguments must specify exactly one complete area of memory that was 
allocated by a call to kmem_alloc or kmem_zalloc (that is, the memory cannot be 
freed piecemeal). 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

kmem_alloc(D3DK), kmem_zalloc(D3DK) 
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NAME 

kvtoppid - get physical page ID for kernel virtual address 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/vmparam.h> 

ppid_t kvtoppid (caddr_t addr)} 

ARGUMENTS 

addr The kernel virtual address for which the physical page ID is to be 
returned. 

DESCRIPTION 

This routine can be used to obtain a physical page ID suitable to be used as the 
return value of the driver's imnap(D2DK) entry point, kvtoppid returns the phy¬ 
sical page ID corresponding to the virtual address addr. 

A physical page ID is a machine-specific token that uniquely identifies a page of 
physical memory in the system (either system memory or device memory.) No 
assumptions should be made about the format of a physical page ID. 

RETURN VALUE 

If addr is valid, the corresponding physical page ID is returned. Otherwise, 
NOPAGE is returned. 

LEVEL 

Base or interrupt. 

NOTES 

Does not sleep. 

Driver defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

inmap(D2DK), intro(D3DK), phystoppid(D3D) 
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NAME 

LOCK - acquire a basic lock 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ksynch.h> 

pl_t LOCK(lock_t *lockp, pl_t pi): 

ARGUMENTS 

lockp 

pi 


DESCRIPTION 

LOCK sets the interrupt priority level in accordance with the value specified by pi 
(if required by the implementation) and acquires the lock specified by lockp. If 
the lock is not immediately available, the caller will wait until the lock is avail¬ 
able. It is implementation defined whether the caller will block during the wait. 
Some implementations may cause the caller to spin for the duration of the wait, 
while on others the caller may block at some point. 

RETURN VALUE 

Upon acquiring the lock, LOCK returns the previous interrupt priority level 
(plbase - plhi). 

LEVEL 

Base or Interrupt. 

NOTES 

Basic locks are not recursive. A call to LOCK attempting to acquire a lock that is 
currently held by the calling context will result in deadlock. 

Calls to LOCK should honor the ordering defined by the lock hierarchy [see 
L0CK_ALL0C(D3DK)] in order to avoid deadlock. 

Driver defined sleep locks may be held across calls to this function. 

Driver defined basic locks and read/write locks may be held across calls to this 
function subject to the hierarchy and recursion restrictions described above. 

When called from interrupt level, the pi argument must not specify a priority 
level below the level at which the interrupt handler is running. 

SEE ALSO 

lock_alloc(D3DK), lock_dealloc(D3DK), trylock(D3DK), unlcx:k(D3DK) 


Pointer to the basic lock to be acquired. 

The interrupt priority level to be set while the lock is held by the 
caller. Because some implementations require that interrupts that 
might attempt to acquire the lock be blocked on the processor on 
which the lock is held, portable drivers must specify a pi value that is 
sufficient to block out any interrupt handler that might attempt to 
acquire this lock. See the description of the minjpl argument to 
L0CK_ALL0C(D3DK) for additional discussion and a list of the valid 
values for pi. Implementations which do not require that the interrupt 
priority level be raised during lock acquisition may choose to ignore 
this argument. 
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The ordering of pldisk and plstr relative to each other is not 
defined. 

Setting a given priority level will block interrupts associated with that 
level as well as any levels that are defined to be less than or equal to 
the specified level. In order to be portable a driver should not acquire 
locks at different priority levels where the relative order of those prior¬ 
ity levels is not defined above. 

The min_pl argument should specify a priority level that would be 
sufficient to block out any interrupt handler that might attempt to 
acquire this lock. In addition, potential deadlock problems involving 
multiple locks should be considered when defining the minjpl value. 
For example, if the normal order of acquisition of locks A and B (as 
defined by the lock hierarchy) is to acquire A first and then B, lock B 
should never be acquired at a priority level less than the minjpl for 
lock A. Therefore, the min_pl for lock B should be greater than or 
equal to the min_pl for lock A. 

Note that the specification of minj)l with a LCX::k_ALLCX! call does not 
actually cause any interrupts to be blocked upon lock acquisition, it 
simply asserts that subsequent LOCK calls to acquire this lock will pass 
in a priority level at least as great as minjpl. 

Ikinfop Pointer to a lkinfo(D4DK) structure. The lk_naine member of the 
Ikinfo structure points to a character string defining a name that will 
be associated with the lock for the purpose of statistics gathering. The 
name should begin with the driver prefix and should be unique to the 
lock or group of locks for which the driver wishes to collect a 
uniquely identifiable set of statistics (i.e. if a given name is shared by a 
group of locks, the statistics of individual locks within the group will 
not be uniquely identifiable). There are no flags defined within the 
lk_f lags member of the Ikinfo structure for use with IiOCK_ALLOC. 

The Ikinfop pointer is recorded in a statistics buffer along with the lock 
statistics when the driver is compiled with the DEBUG and _MPSTATS 
compilation options defined. A given Ikinfo structure may be shared 
among multiple basic locks and read/write locks but a Ikinfo struc¬ 
ture may not be shared between a basic lock and a sleep lock. The 
caller must ensure that the lk_flags and lk_pad members of the 
Ikinfo structure are zeroed out before passing it to IiCX:!K_ALLOC. 

flag Specifies whether the caller is willing to sleep waiting for memory. If 

flag is set to KM_SLEEP, the caller will sleep if necessary until sufficient 
memory is available. If flag is set to KM__NOSLEEP, the caller will not 
sleep, but IiCX:k_ALIiOC will return NULL if sufficient memory is not 
immediately available. Under the _MPSTATS compilation option, if 
KM_NOSLEEP is specified and sufficient memory can be immediately 
allocated for the lock itself but not for an accompanying statistics 
buffer, LOCK_ALLOC will return a pointer to the allocated lock but indi¬ 
vidual statistics will not be collected for the lock. 
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NAME 

LCX:k_DEALLOC - deallocate an instance of a basic lock 

SYNOPSIS 

#include <sys/types.h> 
ttinclude <sys/ksynch.h> 

void riOCK_DEALLOC(lock_t *lockp) ^ 

ARGUMENTS 

lockp Pointer to the basic lock to be deallocated. 

DESCRIPTION 

IjOCK_deallC)C deallocates the basic lock specified by lockp. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Attempting to deallocate a lock that is currently locked or is being waited for is 
an error and will result in undefined behavior. 

Driver defined basic locks (other than the one being deallocated), read/write 
locks, and sleep locks may be held across calls to this function. 

SEE ALSO 

LCX:K(D3DK), Ii0CK_ALL0C(D3DK), TRYIiOCK(D3DK), UNL0CK(D3DK) 
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14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 


if (! INUSE (mimium)) 
break; 

if (itlinnum >=; XXXMAXMIN) { 

UNLCX3C(xxxminlock, pi); 
return(ENXIO); 

} else { 

SETINUSE (minnum); 

UNLOCK(xxxminlcxJk, pi); 

*devp = makedevice (getemaj or (*devp), minnxam); 

} 
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NAME 

min - return the lesser of two integers 

SYNOPSIS 

#include <sys/ddi.h> 
int min(int inti, int inti); 

ARGUMENTS 

inti, int2 The integers to be compared. 

DESCRIPTION 

min compares two integers and returns the lesser of the two. If the inti and int2 
arguments are not of the specified type the results are undefined. 

Also, this interface may be implemented in a way that causes the arguments to be 
evaluated multiple times, so callers should beware of side effects. 

RETURN VALUE 

The lesser of the two integers. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

max(D3DK) 
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NAME 

msgpullup - concatenate bytes in a message 

SYNOPSIS 

#include <sys/stream.h> 

mblk_t *msgpullup(inblk_t *mp, int len)} 

ARGUMENTS 

mp Pointer to the message whose blocks are to be concatenated. 

len Number of bytes to concatenate. 

DESCRIPTION 

msgpullup concatenates and aligns the first len data bytes of the message pointed 
to by mp, copying the data into a new message. The original message is unal¬ 
tered. If len equals -1, all data are concatenated. If len bytes of the same mes¬ 
sage type cannot be found, msgpullup fails and returns NULL. 

RETURN VALUE 

On success, a pointer to the new message is returned; on failure, NULL is 
returned. 

LEVEL 

Base or Interrupt 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

allocb(D3DK), msgb(D4DK) 
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Driver-defined sleep locks may be held across calls to this function. 

Buffers allocated via ngeteblk must be freed using either brelse(D3DK) or 
biodone(D3DK). 

SEE ALSO 

biodone(D3DK), biowait(D3DK), brelse(D3DK), geteblk(D3DK), buf (D4DK) 
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NAME 

OTHERQ - get pointer to queue's partner queue 

SYNOPSIS 

#include <sys/stream.h> 
ttinclude <sys/ddi.h> 

queue_t *OTHERQ(queue_t *q): 

ARGUMENTS 

q Pointer to the queue. 

DESCRIPTION 

The OTHERQ function returns a pointer to the other of the two queue structures 
that make up an instance of a STREAMS module or driver. If q points to the 
read queue the write queue will be returned, and vice versa. 

RETURN VALUE 

OTHERQ returns a pointer to a queue's partner. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

RD(D3DK), WR(D3DK) 

EXAMPLE 

This routine sets the minimum packet size, the maximum packet size, the high 
water mark, and the low water mark for the read and write queues of a given 
module or driver. It is passed either one of the queues. This could be used if a 
module or driver wished to update its queue parameters dynamically. 

1 void 

2 set CT parains(queue t *q, long min, long max, ulong_t hi, ulong_t lo) 

3 { 

4 register pl_t pi; 


5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 


pi = freezestr(q); 

(void) strqset(q, QMINPSZ, 0, min); 

(void) strqset(q, QMAXPSZ, 0, max); 

(void) strqset(q, QHIWAT, 0, hi); 

(void) strqset(q, QLOWAT, 0, lo); 

(void) strqset (OTHERQ(q), QMINPSZ, 0, min) ; 
(void) strqset (OTHERQ (q), QMAXPSZ, 0, max) ; 
(void) strqset (OTHERQ (q), QHIWAT, 0, hi); 
(void) strqset(OTHERQ(q), QLOWAT, 0, lo); 
unfreezestr(q, pi); 
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NAME 

outl - write a 32 bit long word to a 32 bit I/O port 

SYNOPSIS 

#include <sys/types.h> 

void outl (int port, ulong_t data ); 

ARGUMENTS 

port A valid 32 bit I/O port. 

data The 32 bit value to be written to the port. 

DESCRIPTION 

This function provides a C language interface to the machine instruction that 
writes a 32 bit long word to a 32 bit I/O port using the I/O address space, 
instead of the memory address space. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

This function may not be meaningful on all implementations because some imple¬ 
mentations may not support I/O-mapped I/O. 

SEE ALSO 

Programmer's Reference Manual 
Integrated Software Development Guide 

inb(D3D), inl(D3D), inw(D3D), outb(D3D), outw(D3D), repinsb(D3D), 
repinsd(D3D), repinsw(D3D), repoutsb(D3D), repoutsd(D3D), repoutsw(D3D) 
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NAME 

pcansg - test whether a message is a priority control message 

SYNOPSIS 

ttinclude <sys/types.h> 

#include <sys/stream.h> 

#include <sys/ddi.h> 

int pcansg(uchar_t type): 

ARGUMENTS 

type The type of message to be tested. 

DESCRIPTION 

The pcansg function tests the type of message to determine if it is a priority con¬ 
trol message (also known as a high priority message.) The db_type field of the 
datab(D4DK) structure contains the message type. This field may be accessed 
through the message block using itp->b_datap->db_type. 

RETURN VALUE 

pcansg returns 1 if the message is a priority control message and 0 if the message 
is any other type. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

allocb(D3DK), datab(D4DK), msgb(D4DK), messages(D5DK) 

EXAMPLE 

The service routine processes messages on the queue. If the message is a high 
priority message, or if it is a normal message and the stream is not flow- 
controlled, the message is processed and passed along in the stream. Otherwise, 
the message is placed back on the head of the queue and the service routine 
returns. 

1 xxxsrv(q) 

2 queue_t *q; 

3 { 

4 inblk_t *mp; 

5 while ((nip = getq(q)) != NULL) { 

6 if (pamsg(inp->b_datap->cab_type) II canputnext (q)) { 

7 /* process message */ 

8 putnext (q, mp); 

9 } else { 

10 putbq(q, mp); 

11 return; 

12 } 

13 } 

14 } 


3/91 


Page 1 



phfree(D3DK) 


DDI/DKI 


phfree(D3DK) 


NAME 

phfree - free a pollhead structure 

SYNOPSIS 

#include <sys/poll.h> 
ttinclude <sys/kmem.h> 

void phfree(struct pollhead *php)} 

ARGUMENTS 

php Pointer to the pollhead structure to be freed. The structure pointed 

to by php must have been previously allocated by a call to 
phal loc(D3DK). 

DESCRIPTION 

phfree frees the pollhead structure specified by php, 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

DDI/DKI conforming drivers may only use pollhead structures which have been 
allocated and initialized using phalloc. Use of pollhead structures which have 
been obtained by any other means is prohibited. 

SEE ALSO 

chpoll(D2DK), phalloc(D3DK) 
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RETURN VALUE 

physiock returns 0 if the result is successful, or the appropriate error number on 
failure. If a partial transfer occurs, the uio structure is updated to indicate the 
amount not transferred and an error is returned, physiock returns the ENXIO 
error if an attempt is made to read beyond the end of the device. If a read is per¬ 
formed at the end of the device, 0 is returned. ENXIO is also returned if an 
attempt is made to write at or beyond the end of a the device. EFAULT is 
returned if user memory is not valid. EAGAIN is returned if physiock could not 
lock pages for DMA. 

LEVEL 

Base Only. 

NOTES 

Can sleep. 

Driver-defined basic locks and read/write locks may not be held across calls to 
this function. 

Driver-defined sleep locks may be held across calls to this function. 

Some device drivers need nblocks to be arbitrarily large (for example, for tapes 
whose sizes are unknown). In this case, nblocks should be no larger than (2^^)-l. 

SEE ALSO 

ioctl(D2DK), read(D2DK), strategy(D2DK), write(D2DK), dma_pageio(D3D), 
buf (D4DK), uio(D4DK) 

EXAMPLE 

See dina_pageio(D3D) for an example of physiock. 
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NAME 

physinap_f ree - free virtual address mapping for physical addresses 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/kmem.h> 

void physiriap_free(caddr_t vaddr, ulong_t nbytes, uint_t flags): 

ARGUMENTS 

vaddr Virtual address for which the mapping will be released. 
nbytes Number of bytes in the mapping. 
flags For future use (must be set to 0.) 

DESCRIPTION 

physmap_free releases a mapping allocated by a previous call to physmap. The 
nbytes argument must be identical to that given to physmap. Currently, no flags 
are supported and the flags argument must be set to zero. Generally, 
physmap_free will never be called, since drivers usually keep the mapping for¬ 
ever, but it is provided if a driver wants to d 5 mamically allocate and free map¬ 
pings. 

RETURN VALUE 

None. 


LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

physmap(D3D) 
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NAME 

pollwakeup - inform polling processes that an event has occurred 

SYNOPSIS 

#include <sys/poll.h> 

void pollwakeup (struct pollhead short event)} 

ARGUMENTS 

ipkp Pointer to a pollhead structure. 

event Event to notify the process about. 

DESCRIPTION 

The pollwakeup function provides non-STREAMS character drivers with a way 
to notify processes polling for the occurrence of an event, pollwakeup should be 
called from the driver for each occurrence of an event. Events are described in 
chpol 1 (D2DK). 

The pollhead structure will usually be associated with the driver's private data 
structure for the particular minor device where the event has occurred. 

RETURN 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

pollwakeup should only be called with one event at a time. 

SEE ALSO 

chpol 1(D2DK) 

poll(2) in the Programmer's Reference Manual 
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NAME 

proc_ref - obtain a reference to a process for signaling 

SYNOPSIS 

void *proc_ref(); 

DESCRIPTION 

A non-STREAMS character driver can call proc_ref to obtain a reference to the 
process in whose context it is running. The value returned can be used in subse¬ 
quent calls to proc_signal(D3DK) to post a signal to the process. The return 
value should not be used in any other way (i.e. the driver should not attempt to 
interpret its meaning.) 

RETURN VALUE 

An identifier that can be used in calls to proc_signal and proc_unref (D3DK). 

LEVEL 

Base only. 

NOTES 

Processes can exit even though they are referenced by drivers. In this event, 
reuse of the identifier will be deferred until all driver references are given up. 

There must be a matching call to proc_unref for every call to proc_ref, when 
the driver no longer needs to reference the process. This is typically done as part 
of close(D2DK) processing. 

Requires user context. 

Does not sleep. 

Driver defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

proc_signal(D3DK), proc_unref (D3DK) 
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NAME 

proc_miref - release a reference to a process 

SYNOPSIS 

void proc_unref (void *pref ); 

ARGUMENTS 

pref Identifier obtained by a previous call to proc_ref (D3DK). 

DESCRIPTION 

The proc_unref function can be used to release a reference to a process 
identified by the parameter pref. There must be a matching call to proc_unref 
for every previous call to proc_ref(D3DK). 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Processes can exit even though they are referenced by drivers. In this event, 
reuse of pref will be deferred until all driver references are given up. 

Does not sleep. 

Driver defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

proc_ref (D3DK), proc_signal(D3DK) 
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NAME 

put - call a put procedure 

SYNOPSIS 

#include <sys/streain.h> 

void put(queue_t inblk_t *mp); 

ARGUMENTS 

q Pointer to a message queue. 

mp Pointer to the message block being passed. 

DESCRIPTION 

put calls the put procedure (put(D2DK) entry point) for the queue specified by q, 
passing it the arguments q and mp. It is typically used by a driver or module to 
call its own put procedure so that the proper accounting is done in the stream. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

The caller cannot have the stream frozen [see freezestr(D3DK)] when calling 
this function. 

Driver defined basic locks, read/write locks, and sleep locks may not be held 
across calls to this function. 

DDI/DKI conforming drivers and modules are no longer permitted to call put 
procedures directly, but must call through the appropriate STREAMS utility 
function—for example, put(D3DK), putnext(D3DK), putctl(D3DK), 
putnextctl(D3DK), qreply(D3DK). put(q, irp) is provided as a DDI/DKI- 
conforming equivalent to a direct call to a put procedure, which is no longer 
allowed. 

SEE ALSO 

put(D2DK), putctl(D3DK), putctll(D3DK), putnext(D3DK), 
putnextctl(D3DK), putnextctll(D3DK), qreply(D3DK) 
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NAME 

putctl - send a control message to a queue 

SYNOPSIS 

#include <sys/stream.h> 

int putctl (queue_t *q, int type ); 

ARGUMENTS 

q Pointer to the queue to which the message is to be sent. 

type Message type (must be control). 

DESCRIPTION 

putctl tests the type argument to make sure a data type has not been specified, 
and then attempts to allocate a message block, putctl fails if type is M_DATA, 
M_PROTO, or M_PCPROTO, or if a message block cannot be allocated. If successful, 
putctl calls the put(D2DK) routine of the queue pointed to by q, passing it the 
allocated message. 

RETURN VALUE 

On success, 1 is returned. Otherwise, if type is a data type, or if a message block 
cannot be allocated, 0 is returned. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

The caller cannot have the stream frozen [see freezestr(D3DK)] when calling 
this function. 

Driver-defined basic locks, read/write locks, and sleep locks may not be held 
across calls to this function. 

The q argument to putctl and putnextctl(D3DK) may not reference ci_next 
(e.g. an argument of q->q_next is erroneous on a multiprocessor and is disal¬ 
lowed by the DDI/DKI). putnextctl (q, type) is provided as a 
multiprocessor-safe equivalent to the common call putctl(q->q_next, type), 
which is no longer allowed. 

SEE ALSO 

put(D2DK), put(D3DK), putctl 1(D3DK), putnextctl(D3DK), 
putnextct 11(D3DK) 

EXAMPLE 

The pass_ctl routine is used to pass control messages to one's own queue. 
M_BREAK messages are handled with putctl (line 9). putctll (line 11) is used 
for M_DELAY messages, so that param can be used to specify the length of the 
delay. If an invalid message ty^pe is detected, pass_ctl returns 0, indicating 
failure (line 13). 

1 int 

2 pass_ctl (wrq, type, param) 

3 queue_t *wrq; 

4 uchar_t type; 

5 uchar_t param; 
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NAME 

putctll - send a control message with a one-byte parameter to a queue 

SYNOPSIS 

#include <sys/stream.h> 

int putctll (queue_t *q, int type, int par am ); 

ARGUMENTS 

q Pointer to the queue to which the message is to be sent. 

type Message type (must be control). 

param One-byte parameter. 

DESCRIPTION 

putctll, like putctl(D3DK), tests the type argument to make sure a data type 
has not been specified, and attempts to allocate a message block. The param 
parameter can be used, for example, to specify the signal number when an 
M_PCSIG message is being sent, putctll fails if type is M_DATA, M_PROTO, or 
M_PCPROTO, or if a message block cannot be allocated. If successful, putctll calls 
the put(D2DK) routine of the queue pointed to by q, passing it the allocated mes¬ 
sage. 

RETURN VALUE 

On success, 1 is returned. Otherwise, if type is a data type, or if a message block 
cannot be allocated, 0 is returned. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

The caller cannot have the stream frozen [see freezestr(D3DK)] when calling 
this function. 

Driver-defined basic locks, read/write locks, and sleep locks may not be held 
across calls to this function. 

The q argument to putctll and putnextctll(D3DK) may not reference q_next 
(e.g. an argument of q->qi_next is erroneous on a multiprocessor and is disal¬ 
lowed by the DDI/DKI). putnextctll(q, type, param) is provided as a 
multiprocessor-safe equivalent to the common call putctll (q->q_next, type, 
param), which is no longer allowed. 

SEE ALSO 

put(D2DK), put(D3DK), putctl(D3DK), putnextctl(D3DK), 
putnextct 11(D3DK) 

EXAMPLE 

See putctl(D3DK) for an example of putctll. 
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NAME 

putnextctl - send a control message to a queue 

SYNOPSIS 

#include <sys/stream.h> 

int putnextctl (queue_t int type ); 

ARGUMENTS 

q Pointer to the queue from which the message is to be sent. 

type Message type (must be control type). 

DESCRIPTION 

putnextctl tests the type argument to make sure a data type has not been 
specified, and then attempts to allocate a message block, putnextctl fails if type 
is M_DATA, M_PROTO, or M_PCPROTO, or if a message block cannot be allocated. If 
successful, putnextctl calls the put(D2DK) procedure of the queue pointed to 
by q->q_next, passing it the allocated message. 

RETURN VALUE 

Upon successful completion, putnextctl returns 1. If type is a data type, or if a 
message block cannot be allocated, 0 is returned. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

The caller cannot have the stream frozen [see freezestr(D3DK)] when calling 
this function. 

Driver defined basic locks, read/write locks, and sleep locks may not be held 
across calls to this function. 

The q argument to putctl(D3DK) and putnextctl may not reference q_next 
(for example, an argument of q-->q_next is erroneous on a multiprocessor and is 
disallowed by the DDI/DKI). putnextctl (q, type) is provided as a 
multiprocessor-safe equivalent to the common call putctl(q->q_next, type), 
which is no longer allowed. 

SEE ALSO 

put(D2DK), put(D3DK), putctl(D3DK), putctll(D3DK), putnextctl 1(D3DK) 

EXAMPLE 

The send_ctl routine is used to pass control messages downstream. M_BREAK 
messages are handled with putnextctl (line 9). putnextctll (line 11) is used 
for M_DELAY messages, so that param can be used to specify the length of the 
delay. If an invalid message type is detected, send_ctl returns 0, indicating 
failure (line 13). 

1 int 

2 send_ctl (wrq, type, param) 

3 queue_t *wrq; 

4 uchar_t type; 

5 uchar_t param; 

6 { 
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NAME 

putnextctll - send a control message with a one byte parameter to a queue 

SYNOPSIS 

#include <sys/stream.h> 

int putnextctll (queue_t int type, int par am) t 

ARGUMENTS 

q Pointer to the queue from which the message is to be sent. 

type Message type (must be control type). 

param One byte parameter. 

DESCRIPTION 

putnextctll tests the type argument to make sure a data type has not been 
specified, and then attempts to allocate a message block, putnextctll fails if 
type is M_DATA, M_PROTO, or M_PCPROTO, or if a message block cannot be allocated. 
If successful, put next ctl calls the put(D2DK) procedure of the queue pointed to 
by q->qjiext, passing it the allocated message with the one byte parameter 
specified by param. 

RETURN VALUE 

Upon successful completion, putnextctll returns 1. If type is a data type, or if a 
message block cannot be allocated, 0 is returned. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

The caller cannot have the stream frozen [see freezestr(D3DK)] when calling 
this function. 

Driver defined basic locks, read/write locks, and sleep locks may not be held 
across calls to this function. 

The q argument to putctll(D3DK) and putnextctll may not reference qL_next 
(for example, an argument of q->q_next is erroneous on a multiprocessor and is 
disallowed by the DDI/DKI). putnextctll (q, type, param) is provided as a 
multiprocessor-safe equivalent to the common call putctll(q->q_next, type, 
param), which is no longer allowed. 

SEE ALSO 

put(D2DK), put(D3DK), putctl(D3DK), putctll(D3DK), putnextctl(D3DK) 

EXAMPLE 

See putnextctl(D3DK) for an example of putnextctll. 
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NAME 

qenable - schedule a queue's service routine to be run 

SYNOPSIS 

#include <sys/stream.h> 
void qenable (qaeue_t *q); 

ARGUMENTS 

q Pointer to the queue. 

DESCRIPTION 

qenable puts the queue pointed to by q on the linked list of those whose service 
routines are ready to be called by the STREAMS scheduler, qenable works 
regardless of whether the service routine has been disabled by a previous call to 
noenable(D3DK). 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

The caller cannot have the stream frozen [see freezestr(D3DK)] when calling 
this function. 

SEE ALSO 

srv(D2DK), enableok(D3DK), noenable(D3DK), queue(D4DK) 

EXAMPLE 

See enableok(D3DK) for an example of the qenable. 
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NAME 

qprocson - enable put and service routines 

SYNOPSIS 

#include <sys/stream.h> 
void qprocson (queue_t *rq); 

ARGUMENTS 

rq Pointer to a read queue. 

DESCRIPTION 

qprocson enables the put and service routines of the driver or module whose 
read queue is pointed to by rq. Prior to the call to qprocson, the put and service 
routines of a newly pushed module or newly opened driver are disabled. For the 
module, messages flow around it as if it were not present in the stream. 

qprocson must be called by the first open of a module or driver after allocation 
and initialization of any resources on which the put and service routines depend. 

RETURN VALUE 

None. 

LEVEL 

Base Level Only. 

NOTES 

May sleep. 

The caller cannot have the stream frozen [see freezestr(D3DK)] when calling 
this function. 

Driver defined basic locks and read/write locks may not be held across calls to 
this function. 

Driver defined sleep locks may be held across calls to this function. 

SEE ALSO 

open(D2DK), put(D2DK), srv(D2DK), qprocsof f (D3DK) 
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NAME 

qsize - find the number of messages on a queue 

SYNOPSIS 

#include <sys/stream.h> 
int qsize(queue_t *q) s 

ARGUMENTS 

q Pointer to the queue to be evaluated. 

DESCRIPTION 

qsize evaluates the queue pointed to by q and returns the number of messages it 
contains. 

RETURN VALUE 

If there are no message on the queue, qsize returns 0. Otherwise, it returns the 
number of messages on the queue. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

The caller cannot have the stream frozen [see freezestr(D3DK)] when calling 
this function. 

SEE ALSO 

msgb(D4DK), queue(D4DK) 
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NAME 

repinsb - read bytes from I/O port to buffer 

SYNOPSIS 

#include <sys/types.h> 

void repinsb (int port, uchar_t *addr, int cnt) ; 

ARGUMENTS 

port A valid 8 bit I/O port. 

addr The address of the buffer where data is stored after cnt reads of the 
1/O port. 

cnt The number of bytes to be read from the I/O port. 

DESCRIPTION 

This function provides a C language interface to the machine instructions that 
read a string of bytes from an 8 bit I/O port using the I/O address space, instead 
of the memory address space. The data from cnt reads of the I/O port is stored 
in the data buffer pointed to by addr. The data buffer should be at least cnt bytes 
in length. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

This function may not be meaningful on all implementations because some imple¬ 
mentations may not support I/O-mapped 1/O. 

SEE ALSO 

Programmer's Reference Manual 
Integrated Software Development Guide 

inb(D3D), ini (DSD), inw(D3D), outb(D3D), out 1 (DSD), outw(D3D), 
repinsd(D3D), repinsw(D3D), repoutsb(D3D), repout sd(D3D), repoutsw(D3D) 
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NAME 

repinsw - read 16 bit words from I/O port to buffer 

SYNOPSIS 

#include <sys/types.h> 

void repinsw (int port, ushort_t *addr, int cnt ); 

ARGUMENTS 

port 

addr 
cnt 

DESCRIPTION 

This function provides a C language interface to the machine instructions that 
read a string of 16 bit short words from a 16 bit 1/O port using the I/O address 
space, instead of the memory address space. The data from cnt reads of the I/O 
port is stored in the data buffer pointed to by addr. The data buffer should be at 
least cnt 16 bit words in length. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

This function may not be meaningful on all implementations because some imple¬ 
mentations may not support 1/O-mapped I/O. 

SEE ALSO 

Programmer's Reference Manual 
Integrated Software Development Guide 

iiib(D3D), ini (DSD), inw(D3D), outb(D3D), out 1 (DSD), outw(D3D), 
repinsb(D3D), repinsd(D3D), repoutsb(D3D), repoutsd(D3D), repoutsw(D3D) 


A valid 16 bit I/O port. 

The address of the buffer where data is stored after cnt reads of the 
I/O port. 

The number of 16 bit words to be read from the 1/O port. 
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NAME 

repoutsd - write 32 bit words from buffer to an 1/O port 

SYNOPSIS 

#include <sys/types.h> 

void repout sd(int port, ulong_t *addr, int cnt ); 

ARGUMENTS 

port A valid 32 bit I/O port. 

addr The address of the buffer from which cnt 32 bit words are written to 
the I/O port. 

cnt The number of 32 bit words to be written to the I/O port. 

DESCRIPTION 

This function provides a C language interface to the machine instructions that 
write a string of 32 bit long words to a 32 bit I/O port using the I/O address 
space, instead of the memory address space, cnt 32 bit words starting at the 
address pointed to by addr are written to the I/O port in cnt write operations. 
The buffer should be at least cnt 32 bit words in length. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

This function may not be meaningful on all implementations because some imple¬ 
mentations may not support I/O-mapped I/O. 

SEE ALSO 

Programmer's Reference Manual 
Integrated Software Development Guide 

inb(D3D), inl(D3D), inw(D3D), outb(D3D), outl(D3D), outw(D3D), 
repinsb(D3D), repinsd(D3D), repinsw(D3D), repoutsb(D3D), repout sw(D3D) 
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NAME 

rmalloc - allocate space from a private space management map 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/map.h> 

#include <sys/ddi.h> 

ulong_t rmalloc (struct map size_t size)} 

ARGUMENTS 

mp Pointer to the map from which space is to be allocated. 

size Number of units of space to allocate. 

DESCRIPTION 

rmalloc allocates space from the private space management map pointed to by 
mp. The map must have been allocated by a call to rmallocmap(D3DK) and the 
space managed by the map must have been added using rmfree(D3DK) prior to 
the first call to rmalloc for the map. 

size specifies the amount of space to allocate and is in arbitrary units. The driver 
using the map places whatever semantics on the units are appropriate for the 
type of space being managed. For example, units may be byte addresses, pages 
of memory, or blocks on a device. 

The system allocates space from the memory map on a first-fit basis and coalesces 
adjacent space fragments when space is returned to the map by rmfree. 

RETURN VALUE 

Upon successful completion, rmalloc returns the base of the allocated space. If 
size units cannot be allocated, 0 is returned. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

rmalloc_wait(D3DK), rTnallocmap(D3DK), rmfree(D3DK), rmfreemap(D3DK) 
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NAME 

rmalloc_wait - allocate space from a private space management map 

SYNOPSIS 

ttinclude <sys/types.h> 
ttinclude <sys/inap.h> 

ulong_t nnalloc_wait(struct map *mp, size_t size)} 

ARGUMENTS 

mp Pointer to map to resource map. 

size Number of units to allocate. 

DESCRIPTION 

rmalloc_wait allocates space from a private map previously allocated using 
rmallocmap(D3DK). rmalloc_wait is identical to rmalloc(D3DK), except that a 
caller to rmalloc_wait will sleep (iminterruptible by signals), if necessary, until 
space becomes available. 

Space allocated using rmalloc_wait may be returned to the map using 
rmfree(D3DK). 

RETURN VALUE 

rmalloc_wait returns the base of the allocated space. 

LEVEL 

Base Level Only. 

NOTES 

May sleep. 

Driver defined basic locks and read/write locks may not be held across calls to 
this function. 

Driver defined sleep locks may be held across calls to this function, but the driver 
writer must be cautious to avoid deadlock between the process holding the lock 
and trying to acquire the resource and another process holding the resource and 
trying to acquire the lock. 

SEE ALSO 

rmalloc(D3DK), rmallocmap(D3DK), rmfree(D3DK), rmfreemap(D3DK) 
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NAME 

rmf reemap - free a private space management map 

SYNOPSIS 

#include <sys/map.h> 

void rmfreemap( struct map *mp); 

ARGUMENTS 

mp Pointer to the map to be freed. The map structure array pointed to by 

mp must have been previously allocated by a call to 
rmal locmap(D3DK). 

DESCRIPTION 

rmf reemap frees the map pointed to by mp. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

DDI/DKI conforming drivers may only use map structures which have been allo¬ 
cated and initialized using rmallocmap. Use of map structures which have been 
obtained by any other means is prohibited. 

Before freeing the map, the caller must ensure that nobody is using space 
managed by the map, and that nobody is waiting for space in the map. 

SEE ALSO 

rmalloc(D3DK), rmalloc_wait(D3DK), rmallocmap(D3DK), rmfree(D3DK) 
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NAME 

rmvq - remove a message from a queue 

SYNOPSIS 

ttinclude <sys/stream.h> 

void nnvq(queue_t inblk_t *mp); 

ARGUMENTS 

q Pointer to the queue containing the message to be removed. 

mp Pointer to the message to remove. 

DESCRIPTION 

rmvq removes a message from a queue. A message can be removed from any¬ 
where in a queue. To prevent modules and drivers from having to deal with the 
internals of message linkage on a queue, either rmvq or getq(D3DK) should be 
used to remove a message from a queue. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

The caller must have the stream frozen [see freezestr(D3DK)] when calling this 
function. 

mp must point to an existing message in the queue pointed to by q, or a system 
panic will occur. 

SEE ALSO 

freezestr(D3DK), getq(D3DK), insq(D3DK), unfreezestr(D3DK) 

EXAMPLE 

See insq(D3DK) for an example of rmvq. 
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The ordering of pldisk and plstr relative to each other is not 
defined. 

Setting a given priority level will block interrupts associated with that 
level as well as any levels that are defined to be less than or equal to 
the specified level. In order to be portable a driver should not acquire 
locks at different priority levels where the relative order of those prior¬ 
ity levels is not defined above. 

The min_pl argument should specify a priority level that would be 
sufficient to block out any interrupt handler that might attempt to 
acquire this lock. In addition, potential deadlock problems involving 
multiple locks should be considered when defining the min_pl value. 
For example, if the normal order of acquisition of locks A and B (as 
defined by the lock hierarchy) is to acquire A first and then B, lock B 
should never be acquired at a priority level less than the min_pl for 
lock A. Therefore, the minj)l for lock B should be greater than or 
equal to the minj)l for lock A. 

Note that the specification of min_pl with a RW_ALLOC call does not 
actually cause any interrupts to be blocked upon lock acquisition, it 
simply asserts that subsequent RW_RDLOCK/RW_VJRIjOCK calls to acquire 
this lock will pass in a priority level at least as great as minjpl. 

Ikinfop Pointer to a lkinfo(D4DK) structure. The lk_name member of the 
Ikinfo structure points to a character string defining a name that will 
be associated with the lock for the purpose of statistics gathering. The 
name should begin with the driver prefix and should be unique to the 
lock or group of locks for which the driver wishes to collect a 
uniquely identifiable set of statistics (i.e. if a given name is shared by a 
group of locks, the statistics of individual locks within the group will 
not be uniquely identifiable). There are no flags defined within the 
lk_flags member of the Ikinfo structure for use with RW_ALLOC. 

The Ikinfop pointer is recorded in a statistics buffer along with the lock 
statistics when the driver is compiled with the DEBUG and _MPSTATS 
compilation options defined. A given Ikinfo structure may be shared 
among multiple read/write locks and basic locks but a Ikinfo struc¬ 
ture may not be shared between a read/write lock and a sleep lock. 
The caller must ensure that the lk_f lags and lk_pad members of the 
Ikinfo structure are zeroed out before passing it to RW_ALliOC. 

flag Specifies whether the caller is willing to sleep waiting for memory. If 

flag is set to KM_SLEEP, the caller will sleep if necessary until sufficient 
memory is available, flag is set to KM_NOSLEEP, the caller will not 
sleep, but RW_ALliCX: will return NULL if sufficient memory is not 
immediately available. Under the _MPSTATS compilation option, if 
KM_NOSLEEP is Specified and sufficient memory can be immediately 
allocated for the lock itself but not for an accompanying statistics 
buffer, RW_ALLOC will return a pointer to the allocated lock but indivi¬ 
dual statistics will not be collected for the lock. 
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NAME 

RW_DEALLOC - deallocate an instance of a read/write lock 

SYNOPSIS 

ttinclude <sys/types.h> 

#include <sys/ksynch.h> 

void RW_DEALliOC(rwlock_t *lockp): 

ARGUMENTS 

lockp Pointer to the read/write lock to be deallocated. 

DESCRIPTION 

RW_DEALLOC deallocates the read/write lock specified by lockp. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Attempting to deallocate a lock that is currently locked or is being waited for is 
an error and will result in undefined behavior. 

Driver defined locks, read/write locks (other than the one being deallocated), and 
sleep locks may be held across calls to this function. 

SEE ALSO 

RW_ALIiOC(D3DK), rw_rdlock(D3DK), rw_tryrdlock(D3DK), 
rw_trywrlock(D3DK), rw_unlock(D3DK), rw_wrlock(D3DK) 
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SEE ALSO 

RW_ALLCX:(D3DK), RW_DEALriOC(D3DK), rw_tryrdlock(D3DK), 
rw_trywrlock(D3DK), rw_unlock(D3DK), RW_WRL0CK(D3DK) 
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NAME 

RW_TRYWRLOCK - try to acquire a read/write lock in write mode 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ksynch.h> 

pl_t RW_TRYWRLOCK(rwlock_t *lockp, pl_t pi ); 

ARGUMENTS 

lockp Pointer to the read/write lock to be acquired. 

pi The interrupt priority level to be set while the lock is held by the 

caller. Because some implementations require that interrupts that 
might attempt to acquire the lock be blocked on the processor on 
which the lock is held, portable drivers must specify a pi value that is 
sufficient to block out any interrupt handler that might attempt to 
acquire this lock. See the description of the minjpl argument to 
RW_ALL0C(D3DK) for additional discussion and a list of the valid 
values for pi. Implementations which do not require that the interrupt 
priority level be raised during lock acquisition may choose to ignore 
this argument. 

DESCRIPTION 

If the lock specified by lockp is immediately available in write mode (no context is 
holding the lock in read mode or write mode), RW_TRYWRLOCK sets the interrupt 
priority level in accordance with the value specified by pi (if required by the 
implementation) and acquires the lock in write mode. If the lock is not immedi- 
ately available in write mode, the function returns without acquiring the lock. 

RETURN VALUE 

If the lock is acquired, RW_TRYWRLOCK returns the previous interrupt priority level 
(plbase - plhi). If the lock is not acquired the value invpl is returned. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

RW_TRYWRLOCK may be used to acquire a lock in a different order from the order 
defined by the lock hierarchy. 

Driver defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

When called from interrupt level, the pi argument must not specify a priority 
level below the level at which the interrupt handler is running. 

SEE ALSO 

rw_allcx:(D3DK), rw_dealloc(D3DK), rw_rdlock(D3DK), 
rw_tryrdlock(D3DK), rw_unlock(D3DK), rw_wrlock(D3DK) 
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NAME 

RW_WRIiOCK - acquire a read/write lock in write mode 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ksynch.h> 

pl_t RW_WRLOCK(rwlock_t *lockp,pl_t pi) j 

ARGUMENTS 

lockp Pointer to the read/write lock to be acquired. 

pi The interrupt priority level to be set while the lock is held by the 

caller. Because some implementations require that interrupts that 
might attempt to acquire the lock be blocked on the processor on 
which the lock is held, portable drivers must specify a pi value that is 
sufficient to block out any interrupt handler that might attempt to 
acquire this lock. See the description of the min_pl argument to 
RW_ALL0C(D3DK) for additional discussion and a list of the valid 
values for pi. Implementations which do not require that the interrupt 
priority level be raised during lock acquisition may choose to ignore 
this argument. 

DESCRIPTION 

RW_WRLOCK sets the interrupt priority level in accordance with the value specified 
by pi (if required by the implementation) and acquires the lock specified by lockp 
in write mode. If the lock cannot be acquired immediately in write mode, the 
caller will wait until the lock is available in write mode. (A read/write lock is 
available in write mode when the lock is not held by any context). It is imple¬ 
mentation defined whether the caller will block during the wait. Some imple¬ 
mentations may cause the caller to spin for the duration of the wait, while on 
others the caller may block at some point. 

RETURN VALUE 

Upon acquiring the lock, RW_WRLOCK returns the previous interrupt priority level 
(plbase - plhi). 

LEVEL 

Base or Interrupt. 

NOTES 

Read/write locks are not recursive. A call to LCXIK attempting to acquire a lock 
that is currently held by the calling context may result in deadlock. 

Calls to RW_WRLOCK should honor the ordering defined by the lock hierarchy [see 
RW_ALL0C(D3DK)] in order to avoid deadlock. 

Driver defined sleep locks may be held across calls to this function. 

Driver defined basic locks and read/write locks may be held across calls to this 
function subject to the hierarchy and recursion restrictions described above. 

When called from interrupt level, the pi argument must not specify a priority 
level below the level at which the interrupt handler is running. 
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NAME 

SAMESTR - test if next queue is same type 

SYNOPSIS 

#include <sys/stream.h> 
int SAMESTR (queue_t *q)} 

ARGUMENTS 

q Pointer to the queue. 

DESCRIPTION 

The SAMESTR function is used to see if the next queue in a stream (if it exists) is 
the same type as the current queue (that is, both are read queues or both are 
write queues). This can be used to determine the point in a STREAMS-based 
pipe where a read queue is linked to a write queue. 

RETURN VALUE 

SAMESTR returns 1 if the next queue is the same type as the current queue. It 
returns 0 if the next queue does not exist or if it is not the same type. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

The caller cannot have the stream frozen [see freezestr(D3DK)] when calling 
this function. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

The argument q may not reference q_next (for example, an argument of q- 
>q_next is erroneous on a multiprocessor and is disallowed by the DDI/DKI). 

SEE ALSO 

0THERQ(D3DK) 

EXAMPLE 

See the put(D2DK) manual page for an example of SAMESTR. 


3/91 


Page 1 



SLEEP ALLOC (D3DK) 


DDI/DKI 


SLEEP_ALLOC(D3DK) 


LEVEL 

Base only ii flag is set to KM_SLEEP. Base or interrupt if flag is set to KM_NOSLEEP. 

NOTES 

May sleep if flag is set to KM_SLEEP. 

Driver defined basic locks and read/write locks may be held across calls to this 
function if flag is KM_NOSLEEP but may not be held ii flag is KM_SLEEP. 

Driver defined sleep locks may be held across calls to this function regardless of 
the value oi flag. 

SEE ALSO 

SLEEP_DEALL0C(D3DK), SLEEP_IiOCK(D3DK), SLEEP_L0CK_SIG(D3DK), 
SLEEP_IiOCKAVAIL(D3DK), SLEEP_L0CK0WNED(D3DK), SLEEP_TRYIiOCK(D3DK), 
SLEEP_UNIiOCK(D 3DK), lkinfo(D4DK) 
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NAME 

SLEEP_rjOCK - acquire a sleep lock 

SYNOPSIS 

ttinclude <sys/ksynch.h> 


void SLEEP_LOCK(sleep_t *lockp, ±nt priority); 


ARGUMENTS 

lockp 

priority 


Pointer to the sleep lock to be acquired. 

A hint to the the scheduling policy as to the relative priority the caller 
wishes to be assigned while running in the kernel after waking up. 
The valid values for this argument are as follows; 


pridisk 

prinet 

pritty 

pritape 

prihi 

primed 

prilo 


Priority appropriate for disk driver. 
Priority appropriate for network driver. 
Priority appropriate for terminal driver. 
Priority appropriate for tape driver. 
High priority. 

Medium priority. 

Low priority. 


Drivers may use these values to request a priority appropriate to a 
given type of device or to request a priority that is high, medium or 
low relative to other activities within the kernel. 

It is also permissible to specify positive or negative offsets from the 
values defined above. Positive offsets result in more favorable prior¬ 
ity. The maximum allowable offset in all cases is 3 (e.g. pridisk+3 
and pridisk-3 are valid values but pridisk+4 and pridisk-4 are 
not valid). Offsets can be useful in defining the relative importance of 
different locks or resources that may be held by a given driver. In 
general, a higher relative priority should be used when the caller is at¬ 
tempting to acquire a highly contended lock or resource, or when the 
caller is already holding one or more locks or kernel resources upon 
entry to SLEEP_LOCK. 

The exact semantic of the priority argument is specific to the schedul¬ 
ing class of the caller, and some scheduling classes may choose to ig¬ 
nore the argument for the purposes of assigning a scheduling priority. 

DESCRIPTION 

SLEEP_IjOCK acquires the sleep lock specified by lockp. If the lock is not immedi¬ 
ately available, the caller is put to sleep (the caller's execution is suspended and 
other processes may be scheduled) until the lock becomes available to the caller, 
at which point the caller wakes up and returns with the lock held. 

The caller will not be interrupted by signals while sleeping inside SLEEP_LOCK. 

RETURN VALUE 

None. 
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SLEEP LOCKAVAIL (D3DK) 


NAME 

SLEEP_LOCKAVAIL - query whether a sleep lock is available 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ksynch.h> 

bool_t SLEEP_LOCKAVAIL(sleep_t *lockp)} 

ARGUMENTS 

lockp Pointer to the sleep lock to be queried. 

DESCRIPTION 

SLEEP_i:jOCKAVAIL returns an indication of whether the sleep lock specified by 
lockp is currently available. 

The state of the lock may change and the value returned may no longer be valid 
by the time the caller sees it. The caller is expected to understand that this is 
"stale data" and is either using it as a heuristic or has arranged for the return 
value to be meaningful by other means. 

RETURN VALUE 

SLEEP_LOCKAVAIL returns TRUE (a non-zero value) if the lock was available or 
FALSE (zero) if the lock was not available. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

SLEEP_ALL0C(D3DK), SLEEP_DEALIiOC(D3DK), SLEEP_L0CK(D3DK), 
SLEEP_L0CK_SIG(D3DK), SLEEP_L0CK0WNED(D3DK), SLEEP_TRYIiOCK(D3DK), 
SLEEP_UNL0CK(D3DK) 
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DDI/DKI 


SLEEP LOCK SIG (D3DK) 


NAME 

SLEEP_IiOCK_SIG - acquire a sleep lock 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ksynch.h> 


bool_t SLEEP_LOCK_SlG(sleep_t *lockp, int priority)} 


ARGUMENTS 

lockp 

priority 


Pointer to the sleep lock to be acquired. 

A hint to the the scheduling policy as to the relative priority the caller 
wishes to be assigned while running in the kernel after waking up. 
The valid values for this argument are as follows: 


pridisk 

prinet 

pritty 

pritape 

prihi 

primed 

prilo 


Priority appropriate for disk driver. 
Priority appropriate for network driver. 
Priority appropriate for terminal driver. 
Priority appropriate for tape driver. 
High priority. 

Medium priority. 

Low priority. 


Drivers may use these values to request a priority appropriate to a 
given type of device or to request a priority that is high, medium or 
low relative to other activities within the kernel. 

It is also permissible to specify positive or negative offsets from the 
values defined above. Positive offsets result in more favorable prior¬ 
ity. The maximum allowable offset in all cases is 3 (e.g. pridisk+3 
and pridisk-3 are valid values but pridisk+4 and pridisk-4 are 
not valid). Offsets can be useful in defining the relative importance of 
different locks or resources that may be held by a given driver. In 
general, a higher relative priority should be used when the caller is at¬ 
tempting to acquire a highly contended lock or resource, or when the 
caller is already holding one or more locks or kernel resources upon 
entry to SLEEP_LOCK_SIG. 

The exact semantic of the priority argument is specific to the schedul¬ 
ing class of the caller, and some scheduling classes may choose to ig¬ 
nore the argument for the purposes of assigning a scheduling priority. 

DESCRIPTION 

SLEEP_L0CK_SIG acquires the sleep lock specified by lockp. If the lock is not 
immediately available, the caller is put to sleep (the caller's execution is 
suspended and other processes may be scheduled) until the lock becomes avail¬ 
able to the caller, at which point the caller wakes up and returns with the lock 
held. 

SLEEP_IiCK:k_SIG may be interrupted by a signal, in which case it may return 
early without acquiring the lock. 
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SLEEP TRYLOCK (D3DK) 


NAME 

SLEEP_TRYLCX::k - try to acquire a sleep lock 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ksynch.h> 

bool_t SLEEP_TRYIiOCK(sleep_t *lockp): 

ARGUMENTS 

lockp Pointer to the sleep lock to be acquired. 

DESCRIPTION 

If the lock specified by lockp is immediately available (can be acquired without 
sleeping) SLEEP_TRYLOCK acquires the lock. If the lock is not immediately avail¬ 
able, the function returns without acquiring the lock. 

RETURN VALUE 

SLEEP_TRYLOCK returns TRUE (a non-zero value) if the lock is successfully 
acquired or FALSE (zero) if the lock is not acquired. 

LEVEL 

Base Level Only. 

NOTES 

Does not sleep. 

Driver defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

SLEEP_ALL0C(D3DK), SLEEP_DEALIiOC(D3DK), sleep_lock(D3DK), 
sleep_lock_sig(D3DK), sleep_lockavail(D3DK), sleep_lockowned(D3DK), 
sleep_unlock(D3DK) 
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DDI 


spl(D3D) 


NAME 

spl - block/allow interrupts on a processor 

SYNOPSIS 

pl_t splbase(); 
pl_t spltimeout(); 
pl_t spldiskO; 
pl_t splstrO; 
pl_t splhi (); 

pl_t splx(pl_t oldlevel): 

ARGUMENTS 

oldlevel Last set priority value (only splx has an input argument). 

DESCRIPTION 

The spl functions block or allow servicing of interrupts on the processor on 
which the function is called. Hardware devices are assigned to interrupt priority 
levels depending on the type of device. Each spl function which blocks inter¬ 
rupts is associated with some machine dependent interrupt priority level and will 
prevent interrupts occurring at or below this priority level from being serviced on 
the processor on which the spl function is called. 

On a multiprocessor system, interrupts may be serviced by more than one proces¬ 
sor and, therefore, use of a spl function alone is not sufficient to prevent inter¬ 
rupt code from executing and manipulating driver data structures during a criti¬ 
cal section. Drivers that must prevent execution of interrupt-level code in order 
to protect the integrity of their data should use basic locks or read/write locks for 
this purpose [see L0 CK_all 0C(D3DK) or RW_ALL0C(D3DK)]. 

The spl functions include the following: 


splbase 

spltimeout 

spldisk 

splstr 

splhi 


Block no interrupts. 

Block functions scheduled by itimeout and dtimeout. 
Block disk device interrupts. 

Block STREAMS interrupts. 

Block all interrupts. 


Calling a given spl function will block interrupts specified for that function as 
well as interrupts at equal and lower levels. The notion of low vs. high levels 
assumes a defined order of priority levels. The following partial order is defined: 

splbase <= spltimeout <= spldisk,splstr <= splhi 
The ordering of spldisk and splstr relative to each other is not defined. 

RETURN VALUE 

All spl functions return the previous priority level. 

NOTES 

All spl functions do not sleep. 

Driver defined basic locks and read/write locks may be held across calls to these 
functions, but the spl call must not cause the priority level to be lowered below 
the level associated with the lock. 
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strlog(D3DK) 


NAME 

strlog - submit messages to the log driver 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/stream.h> 
ttinclude <sys/strlog.h> 

#include <sys/log.h> 

int strlog (short mid, short sid, char level, ushort_t flags, 
char *fmt, ... /* args V); 

ARGUMENTS 

mid 

sid 
level 
flags 


fmt 
args 

DESCRIPTION 

strlog submits formatted messages to the log(7) driver. The messages can be 
retrieved with the getmsg(2) system call. The flags argument specifies the type of 
the message and where it is to be sent. strace(lM) receives messages from the 
log driver and sends them to the standard output. strerr(lM) receives error 
messages from the log driver and appends them to a file called 
/var/adm/streams/error.mm-dd, where mm-dd identifies the date of the error 
message. 

RETURN VALUE 

strlog returns 0 if the message is not seen by all the readers, 1 otherwise. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 


Identification number of the module or driver submitting the message. 
Identification number for a particular minor device. 

Tracing level for selective screening of low priority messages. 

Bitmask of flags indicating message purpose. Valid flags are: 

SL_ERROR Message is for error logger. 

SL_TRACE Message is for tracing. 

SL_CONSOLE Message is for console logger. 

SL_N0TIFY If SL_ERROR is also set, mail copy of message to 
system administrator. 

SL_FATAL Modifier indicating error is fatal. 

SL_WARN Modifier indicating error is a warning. 

SL_NOTE Modifier indicating error is a notice. 

print f(3S) style format string. %s, %e, %g, and %G formats are not 
allowed. 

Zero or more arguments to print f (maximum of NL06ARGS, currently 
three). 
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strqget(D3DK) 


NAME 

strqget - get information about a queue or band of the queue 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/stream.h> 

int strqget (queue_t qf ields_t what, uchaocjc pri, long *valp)! 

ARGUMENTS 

q Pointer to the queue. 

what The field of the queue about which to return information. Valid 
values are: 

QHIWAT High water mark of the specified priority band. 

QLOWAT Low water mark of the specified priority band. 

QMAXPSZ Maximum packet size of the specified priority band. 
QMINPSZ Minimum packet size of the specified priority band. 

QCOUNT Number of bytes of data in messages in the specified prior¬ 
ity band. 

QFIRST Pointer to the first message in the specified priority band. 
QLAST Pointer to the last message in the specified priority band. 
QFLAG Flags for the specified priority band [see queue(D4DK)]. 
pri Priority band of the queue about which to obtain information. 

valp Pointer to the memory location where the value is to be stored. 

DESCRIPTION 

strqget gives drivers and modules a way to get information about a queue or a 
particular priority band of a queue without directly accessing STREAMS data 
structures. 

RETURN VALUE 

On success, 0 is returned. An error number is returned on failure. The actual 
value of the requested field is returned through the reference parameter, valp, 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

The caller must have the stream frozen [see freezestr(D3DK)] when calling this 
function. 

SEE ALSO 

freezestr(D3DK), strqset(D3DK), unfreezestr(D3DK), queue(D4DK) 
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SV ALLOC (D3DK) 


NAME 

SV_ALLOC - allocate and initialize a s 5 mchronization variable 

SYNOPSIS 

ttinclude <sys/kmeni.h> 

#include <sys/ksynch.h> 

sv_t *SV_ALLOC(int 

ARGUMENTS 

flag Specifies whether the caller is willing to sleep waiting for memory. If 

flag is set to km_SLiEEP, the caller will sleep if necessary until sufficient 
memory is available. If flag is set to KM_NOSLEEP, the caller will not 
sleep, but SV_ALLCX:! will return NULL if sufficient memory is not 
immediately available. 

DESCRIPTION 

SV_ALLOC dynamically allocates and initializes an instance of a synchronization 
variable. 

RETURN VALUE 

Upon successful completion, SV_ALLOC returns a pointer to the newly allocated 
synchronization variable. If KM_NOSLEEP is specified and sufficient memory is not 
immediately available, SV_ALLOC returns a NULL pointer. 

LEVEL 

Base only ii flag is set to KM_SLEEP. Base or interrupt ii flag is set to KM_NOSLEEP. 

NOTES 

May sleep if flag is set to KM_SLEEP. 

Driver defined basic locks and read/write locks may be held across calls to this 
function if flag is KM_NOSLEEP but may not be held if flag is KM_SLEEP. 

Driver defined sleep locks may be held across calls to this function regardless of 
the value oi flag. 

SEE ALSO 

sv_broadcast(D3DK), sv_dealloc(D3DK), SV_SIGNAL(D3DK), SV_WAIT(D3DK), 
SV_WAIT_SIG(D3DK) 
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SV DEALLOC(D3DK) 


NAME 

SV_DEALLCXI - deallocate an instance of a synchronization variable 

SYNOPSIS 

#include <sys/ksynch.h> 
void SV_DEALLOC(sv_t *SVp) j 

ARGUMENTS 

lockp Pointer to the synchronization variable to be deallocated. 

DESCRIPTION 

sy_DEALLOC deallocates the synchronization variable specified by svp. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

sv_alloc(D3DK), sv_broadcast(D3DK), sv_signal(D3DK), SV_WAIT(D3DK), 
SV_WAIT_SIG(D3DK) 
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SV WAIT(D3DK) 


NAME 

SV_WAIT - sleep on a synchronization variable 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ksynch.h> 


void SV_WAIT(sv_t *svp, int priority, loclfiJo *lkp) j 


ARGUMENTS 

svp 

priority 


Pointer to the synchronization variable on which to sleep. 

A hint to the the scheduling policy as to the relative priority the caller 
wishes to be assigned while running in the kernel after waking up. 
The valid values for this argument are as follows: 


pridisk 

prinet 

pritty 

pritape 

prihi 

primed 

prilo 


Priority appropriate for disk driver. 
Priority appropriate for network driver. 
Priority appropriate for terminal driver. 
Priority appropriate for tape driver. 
High priority. 

Medium priority. 

Low priority. 


Drivers may use these values to request a priority appropriate to a 
given type of device or to request a priority that is high, medium or 
low relative to other activities within the kernel. 

It is also permissible to specify positive or negative offsets from the 
values defined above. Positive offsets result in more favorable prior¬ 
ity. The maximum allowable offset in all cases is 3 (e.g. pridisk+3 
and pridisk-3 are valid values but pridisk+4 and pridisk-4 are 
not valid). Offsets can be useful in defining the relative importance of 
different locks or resources that may be held by a given driver. In 
general, a higher relative priority should be used when the caller is 
sleeping waiting for a highly contended kernel resource, or when the 
caller is already holding one or more locks or kernel resources upon 
entry to SV_WAIT. 

The exact semantic of the priority argument is specific to the schedul¬ 
ing class of the caller, and some scheduling classes may choose to ig¬ 
nore the argument for the purposes of assigning a scheduling priority. 

Ikp Pointer to a basic lock which must be locked when SV_WAIT is called. 

The basic lock is released when the calling process goes to sleep, as 
described below. 

DESCRIPTION 

SV_WAIT causes the calling process to go to sleep (the caller's execution is 
suspended and other processes may be scheduled) waiting for a call to 
SV_SIGNAL(D3DK) or SV_BR0ADCAST(D3DK) for the syuchronization variable 
specified by svp. 
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DDI/DKI 


SV WAIT SIG (D3DK) 


NAME 

SV_WAIT_SIG - sleep on a synchronization variable 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ksynch.h> 


bool_t SV_WAIT_SIG(sv_t *svp, int priority, lock_t *lkp); 


ARGUMENTS 

svp 

priority 


Pointer to the synchronization variable on which to sleep. 

A hint to the the scheduling policy as to the relative priority the caller 
wishes to be assigned while running in the kernel after waking up. 
The valid values for this argument are as follows: 


pridisk 

prinet 

pritty 

pritape 

prihi 

primed 

prilo 


Priority appropriate for disk driver. 
Priority appropriate for network driver. 
Priority appropriate for terminal driver. 
Priority appropriate for tape driver. 
High priority. 

Medium priority. 

Low priority. 


Drivers may use these values to request a priority appropriate to a 
given type of device or to request a priority that is high, medium or 
low relative to other activities within the kernel. 

It is also permissible to specify positive or negative offsets from the 
values defined above. Positive offsets result in more favorable prior¬ 
ity. The maximum allowable offset in all cases is 3 (e.g. pridisk+3 
and pridisk-3 are valid values but pridisk+4 and pridisk-4 are 
not valid). Offsets can be useful in defining the relative importance of 
different locks or resources that may be held by a given driver. In 
general, a higher relative priority should be used when the caller is 
sleeping waiting for a highly contended kernel resource, or when the 
caller is already holding one or more locks or kernel resources upon 
entry to SV_WAIT_SIG. 

The exact semantic of the priority argument is specific to the schedul¬ 
ing class of the caller, and some scheduling classes may choose to ig¬ 
nore the argument for the purposes of assigning a scheduling priority. 

Ikp Pointer to a basic lock which must be locked when SV_WAIT_SIG is 

called. The basic lock is released when the calling process goes to 
sleep, as described below. 

DESCRIPTION 

SV_WAIT_SIG causes the calling process to go to sleep (the caller's execution is 
suspended and other processes may be scheduled) waiting for a call to 
SV_SIGNAL(D3DK) or SV_BR0ADCAST(D3DK) for the synchronization variable 
specified by svp. 


3/91 


Page 1 



TRYL0CK{D3DK) 
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TRYL0CK(D3DK) 


NAME 

TRYLOCK - try to acquire a basic lock 

SYNOPSIS 

ttinclude <sys/types.h> 

#include <sys/ksynch.h> 

pl_t TRYLOCK (lock:_t *lockp, pl_t pi)-, 

ARGUMENTS 

lockp Pointer to the basic lock to be acquired. 

pi The interrupt priority level to be set while the lock is held by the 

caller. Because some implementations require that interrupts that 
might attempt to acquire the lock be blocked on the processor on 
which the lock is held, portable drivers must specify a pi value that is 
sufficient to block out any interrupt handler that might attempt to 
acquire this lock. See the description of the min_pl argument to 
L0CK_ALL0C(D3DK) for additional discussion and a list of the valid 
values for pi. Implementations which do not require that the interrupt 
priority level be raised during lock acquisition may choose to ignore 
this argument. 

DESCRIPTION 

If the lock specified by lockp is immediately available (can be acquired without 
waiting) TRYLOCK sets the interrupt priority level in accordance with the value 
specified by pi (if required by the implementation) and acquires the lock. If the 
lock is not immediately available, the function returns without acquiring the lock. 

RETURN VALUE 

If the lock is acquired, TRYLOCK returns the previous interrupt priority level 
(plbase - plhi). If the lock is not acquired the value invpl is returned. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

TRYLOCK may be used to acquire a lock in a different order from the order 
defined by the lock hierarchy. 

Driver defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

When called from interrupt level, the pi argument must not specify a priority 
level below the level at which the interrupt handler is running. 

SEE ALSO 

lock(D3DK), lock_alloc(D3DK), lock_dealloc(D3DK), unlock(D3DK) 
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DDI/DKI 


uiomove(D3DK) 


If addr specifies an address in user space, or if the value of uio_segflg is not 
consistent with the type of address space described by the uio structure, the sys¬ 
tem can panic. 

SEE ALSO 

bcopy(D3DK), copyin(D3DK), copyout(D3DK), ureadc(D3DK), uwritec(D3DK), 
iovec(D4DK), uio(D4DK) 
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DDI/DKI(STREAMS) 


unbufcall(D3DK) 


15 qprocsoff(g); 

16 if (modp->m_type == BUFCALL) 

17 Tiiibufcall (inodp->m_id); 

18 else if (inodp->m_type == TIMEOUT) 

19 untimeout (inodp->m_id); 

20 inodp->m_type = 0; 
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unlinkb(D3DK) 


NAME 

unlinkb - remove a message block from the head of a message 

SYNOPSIS 

#include <sys/stream.h> 
mblk_t *\inlinkb(mblk_t *mp); 

ARGUMENTS 

mp Pointer to the message. 

DESCRIPTION 

unlinkb removes the first message block from the message pointed to by mp. 
The removed message block is not freed. It is the caller's responsibility to free it. 

RETURN VALUE 

xmlinkb returns a pointer to the remainder of the message after the first message 
block has been removed. If there is only one message block in the message, NULL 
is returned. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

linkb(D3DK) 

EXAMPLE 

The routine expects to get passed an M_PROTO T_DATA_IND message. It will 
remove and free the M_PROTO header and return the remaining M_DATA portion of 
the message. 

1 mblk_t * 

2 inakedata(]iip) 

3 niblk_t *irp; 

4 { 

5 mblk_t *ninp; 

6 rmnp = unlinkb (np) ; 

7 freeb(irp); 

8 return(nmp); 

9 } 
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DDI/DKI 


untimeout (D3DK) 


NAME 

untimeout - cancel previous timeout request 

SYNOPSIS 

#include <sys/types.h> 
void untimeout(toid_t id); 

ARGUMENTS 

id Identifier returned from a previous call to dtimeout(D3D) or 

i t imeou t (D3DK). 

DESCRIPTION 

untimeout cancels a pending timeout request. If the untimeout is called while 
the function is running, then untimeout will not return until the function has 
completed. The function that runs as a result of a call to dtimeout or itimeout 
cannot use untimeout to cancel itself. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt, with the following exception: The untimeout can only be per¬ 
formed from interrupt levels less than, or equal to, the level specified when the 
function was scheduled. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may not be held 
across calls to this function if these locks are contended by the function being 
canceled. 

SEE ALSO 

delay(D3DK), dtimeout(D3D), itimeout(D3DK), unbufcall(D3DK) 

EXAMPLE 

See unbufcall(D3DK) for an example of untimeout. 
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uwritec(D3DK) 


NAME 

uwritec - return a character from space described by uio(D4DK) structure 

SYNOPSIS 

#include <sys/uio.h> 
int uwritec (uio_t *uiop)} 

ARGUMENTS 

uiof Pointer to the uio structure. 

DESCRIPTION 

uwritec copies a character from the space described by the uio structure pointed 
to by uiop and returns the character to the caller. 

The uio_segflg member of the uio structure specifies the type of space from 
which the copy is made. If uio_segf Ig is set to UlO_SYSSPACE the character is 
copied from a kernel address. If uio_segf Ig is set to UlO_USERSPACE the char¬ 
acter is copied from a user address. 

If the character is successfully copied, uwritec updates the appropriate members 
of the uio and iovec(D4DK) structures to reflect the copy (uio_offset and 
iov_base are incremented and uio_resid and ioy_len are decremented) and 
returns the character to the caller. 

RETURN VALUE 

If successful, uwritec returns the character. -1 is returned if the space described 
by the uio structure is empty or there is an error. 

LEVEL 

Base only if uio_segflg is set to UI0_USERSPACE. Base or interrupt if 
uio_segf Ig is set to UIO_SYSSPACE. 

NOTES 

May sleep if uio_segf Ig is set to UI0_USERSPACE. 

Driver-defined basic locks and read/write locks may be held across calls to this 
function if uio_segflg is UIO_SYSSPACE but may not be held if uio_segf Ig is 
UIO_USERSPACE. 

Driver-defined sleep locks may be held across calls to this function regardless of 
the value of uio_segf Ig. 

When holding locks across calls to this function, drivers must be careful to avoid 
creating a deadlock. During the data transfer, page fault resolution might result 
in another I/O to the same device. For example, this could occur if the driver 
controls the disk drive used as the swap device. 

SEE ALSO 

uioinove(D3DK), ureadc(D3DK), iovec(D4DK), uio(D4DK) 
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WR(D3DK) 


NAME 

WR - get a pointer to the write queue 

SYNOPSIS 

#include <sys/stream.h> 

#include <sys/ddi.h> 

queue_t *WR(queue_t *q): 

ARGUMENTS 

q Pointer to the queue whose write queue is to be returned. 

DESCRIPTION 

The WR function accepts a queue pointer as an argument and returns a pointer to 
the write queue of the same module. 

RETURN VALUE 

The pointer to the write queue. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

Driver-defined basic locks, read/write locks, and sleep locks may be held across 
calls to this function. 

SEE ALSO 

0THERQ(D3DK), rd(D3DK) 

EXAMPLE 

In a STREAMS open(D2DK) routine, the driver or module is passed a pointer to 
the read queue. The driver or module can store a pointer to a private data struc¬ 
ture in the q_ptr field of both the read and write queues if it needs to identify 
the data structures from its put(D2DK) or srv(D2DK) routines. 

1 extern struct xxx_dev[]; 

2 xxxopen(queue_t *q, dev_t *devp, int flag, int sflag, cred_t *crp) 

3 { 

3 q- >q_ptr = (caddr_t) &xxx_dev [ getminor (*devp) ]; 

4 WR (q) - >q_ptr = (caddr_t) &xxx_dev [ getminor (*devp) ]; 

5 } 
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NAME 

dina_disable - disable recognition of hardware requests on a DMA channel 

SYNOPSIS 

#include <sys/dina.h> 
void dina_disable(int chan): 

ARGUMENTS 

chan Channel to be disabled. 

DESCRIPTION 

dina_disable disables recognition of hardware requests on the DMA channel 
chan. The channel is then released and made available for other use. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

The caller must ensure that it is acting on behalf of the channel owner, and that it 
makes sense to release the channel. 

The caller must ensure that the channel is in use for hardware-initiated DMA 
transfers and not software-initiated transfers. 

SEE ALSO 

diiia_enable(D3X), dma_prog(D3X), dina_cb(D4X) 
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NAME 

dma_f ree_buf - free a previously allocated DMA buffer descriptor 

SYNOPSIS 

#include <sys/dina.h> 

void dina_free_buf (struct dina_buf *dmabufptr); 

ARGUMENTS 

dmahufptr Address of the allocated DMA buffer descriptor to be returned. 

DESCRIPTION 

dina_free_buf frees a DMA buffer descriptor. The dmahufptr argument must 
specify the address of a DMA buffer descriptor previously allocated by 
dma get buf(D3X). 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

SEE ALSO 

dma_get_buf(D3X), dma_buf(D4X) 
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NAME 

dma get buf - allocate a DMA buffer descriptor 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/dina.h> 

struct dma_buf *dma_get_buf(uchar_t mode); 

ARGUMENTS 

mode 


DESCRIPTION 

dm a g et buf allocates memory for a DMA command block structure [see 
dma_buf (D4X)], zeroes it out, and returns a pointer to the structure. 

RETURN VALUE 

dma_get_buf returns a pointer to the allocated DMA control block. If 
DMA_NOSLEEP is Specified and memory for a dma_buf is not immediately avail¬ 
able, dma g et buf returns a NULL pointer. 

LEVEL 

Base only if mode is set to dma_SLEEP. Base or Interrupt if mode is set to 
DMA_NOSLEEP. 

NOTES 

Can sleep if mode is set to dma_sleep. 

SEE ALSO 

dma_free_buf(D3X), dma_buf(D4X) 


Specifies whether the caller is willing to sleep waiting for memory. If 
mode is set to DMA_SLEEP, the caller will sleep if necessary until the 
memory for a dma_buf is available. If mode is set to DMA_NOSLEEP, the 
caller will not sleep, but dma get buf will return NULL if memory for 
a dma_buf is not immediately available. 
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NAME 

dina_get_cb - allocate a DMA command block 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/dina.h> 

struct dina_cb *dina get cbCuchar t mode); 

ARGUMENTS 

mode Specifies whether the caller is willing to sleep waiting for memory. If 
mode is set to DMA_SLEEP, the caller will sleep if necessary until the 
memory for a dina_cb is available. If mode is set to DMA_NOSLEEP, the 
caller will not sleep, but dm a g et cb will return NULL if memory for a 
dina_cb is not immediately available. 

DESCRIPTION 

dma_get_cb allocates memory for a DMA command block structure [see 
dma_cb(D4X)], zeroes it out, and returns a pointer to the structure. 

RETURN VALUE 

dm a g et cb returns a pointer to the allocated DMA control block. If 
DMA_NOSLEEP is Specified and memory for a dma_cb is not immediately available, 
dma get cb returns a NULL pointer. 

LEVEL 

Base only if mode is set to DMA_SLEEP. Base or Interrupt if mode is set to 
DMA_NOSLEEP. 

NOTES 

Can sleep if mode is set to dma_SLEEP. 

SEE ALSO 

dma_f ree_cb(D3X), dma_cb(D4X) 
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NAME 

dina_stop - stop software-initiated DMA operation on a channel and release it 

SYNOPSIS 

ttinclude <sys/dina.h> 
void dina_stop(int chan): 

ARGUMENTS 

chan Channel on which DMA operation is to be stopped. 

DESCRIPTION 

dina_stop stops a software-initiated DMA operation in progress on the channel 
chan. The channel is then released and made available for other use. 

RETURN VALUE 

None. 

LEVEL 

Base or Interrupt. 

NOTES 

Does not sleep. 

The caller must ensure that it is acting on behalf of the channel owner, and that it 
makes sense to release the channel. 

The caller must ensure that the channel is currently in use for software-initiated 
DMA transfers rather than hardware-initiated transfers. 

SEE ALSO 

dma_swsetup(D3X), dina_swstart(D3X), dina_cb(D4X) 
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NAME 

caina_swsetup - program a DMA operation for a subsequent software request 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ditia.h> 

int dma_swsetup(struct dina_cb "^dmacbptr, int chan, uchar_t mode)} 

ARGUMENTS 

dmacbptr Pointer to the DMA command block specifying the DMA operation. 
chan DMA channel over which the operation is to take place. 

mode Specifies whether the caller is willing to sleep waiting to allocate 

desired DMA channel. If mode is set to DMA_SLEEP, the caller will 
sleep if necessary until the requested channel becomes available for its 
use. If mode is set to DMA_N0SLEEP, the caller will not sleep, but 
dina_swsetup will return FALSE if the requested DMA channel is not 
immediately available. 

DESCRIPTION 

dina_swsetup programs the DMA channel chan for the operation specified by the 
DMA command block whose address is given by dmacbptr. Note that 
dina_swsetup does not initiate the DMA transfer. Instead, the transfer will be ini¬ 
tiated by a subsequent request initiated via software by dina_swstart(D3X). 

If dina_swsetup programs the operation successfully, it then calls the procedure 
specified by the proc field of the dina_cb(D4X) structure. It passes as an argu¬ 
ment the value in the procparms field. If proc is set to NULL, then no routine is 
called. 

To program the operation, dina_swsetup requires exclusive use of the specified 
DMA channel. The caller may specify, via the mode argument, whether 
dina_swsetup should sleep waiting for a busy channel to become available. If the 
specified channel is in use and mode is set to DMA_SLEEP, then dina_swsetup will 
sleep until the channel becomes available for its use. Otherwise, if DMA_NOSLEEP 
is specified and the requested channel is not immediately available, dma_swsetup 
will not program the channel, but will simply return a value of FALSE. 

RETURN VALUE 

dma_swsetup returns the value TRUE on success and returns the value FALSE oth¬ 
erwise. 

LEVEL 

Base only if either (1) mode is set to dma_SLEEP or (2) the routine specified by the 
proc field of the dina_cb structure sleeps. Base or Interrupt otherwise. 

NOTES 

Can sleep if mode is set to DMA_SLEEP or if the routine specified by the proc field 
of the <3ina_cb structure sleeps. 

SEE ALSO 

dina_swstart(D3X), <aina_stop(D3X), dina_cb(D4X) 
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NAME 

buf - block I/O data transfer structure 

SYNOPSIS 

ttinclude <sys/types.h> 
ttinclude <sys/page.h> 
ttinclude <sys/proc.h> 

#include <sys/buf.h> 

DESCRIPTION 

The buf structure is the basic data structure for block I/O transfers. Each block 
I/O transfer has an associated buffer header. The header contains all the buffer 
control and status information. For drivers, the buffer header pointer is the sole 
argument to a block driver strategy(D2DK) routine. Do not depend on the size 
of the buf structure when writing a driver. 

It is important to note that a buffer header may be linked in multiple lists simul¬ 
taneously. Because of this, most of the members in the buffer header cannot be 
changed by the driver, even when the buffer header is in one of the drivers' work 
lists. 

Buffer headers may be used by the system to describe a portion of the kernel data 
space for I/O for block drivers. Buffer headers are also used by the system for 
physical I/O for block drivers. In this case, the buffer describes a portion of user 
data space that is locked into memory [see physiock(D3DK)]. 

Block drivers often chain block requests so that overall throughput for the device 
is maximized. The av_forw and the av_back members of the buf structure can 
serve as link pointers for chaining block requests. 

STRUCTURE MEMBERS 


int 

b_flags; 

/* 

Buffer status */ 

struct buf 

*b_forw; 

/* 

Kemel/driver list link */ 

struct buf 

*b_back; 

/* 

Kemel/driver list link */ 

struct buf 

*av_forw; 

/* 

Driver vzork list link */ 

struct buf 

*av_back; 

/* 

Driver work list link */ 

uint_t 

b_bcount; 

/* 

# of bytes to transfer */ 

union { 




caddr_t 

b_addr; 

/* 

Buffer's virtual address */ 

} b_un; 




daddr_t 

b_blkno; 

/* 

Block number on device */ 

uint_t 

b_resid; 

/* 

# of bytes not transferred */ 

clock_t 

b_start; 

/* 

Request start time */ 

struct proc 

*b_proc; 

/* 

Process structure address */ 

long 

b_bufsize; 

/* 

Size of allocated buffer */ 

int 

(*b_iodone)(); 

/* 

Function called by biodone */ 

dev_t 

b_edev; 

/* 

Expanded dev field */ 

void 

*b_private; 

/* 

For driver's use */ 


The members of the buffer header available to test or set by a driver are 
described below: 
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b_resid indicates the number of bytes not transferred because of an error. The 
driver may change this member. 

b_start holds the time the I/O request was started. It is provided for the 
driver's use in calculating response time and is set by the driver. Its type, 
clock_t, is an integral type upon which direct integer calculations can be per¬ 
formed. It represents clock ticks. 

b_proc contains the process structure address for the process requesting an 
unbuffered (direct) data transfer to or from a user data area (this member is set to 
NULL when the transfer is buffered). The process table entry is used to perform 
proper virtual to physical address translation of the b_un.b_addr member [see 
vtop(D3D)]. The driver may not change this member. 

b_bufsize contains the size in bytes of the allocated buffer. The driver may not 
change this member unless the driver acquired the buffer with getrbuf. 

(*b_iodone) identifies a specific driver routine to be called by the system when 
the I/O is complete. If one is specified, the biodone(D3DK) routine does not 
return the buffer to the system. The driver may change this member. 

b_edev contains the external device number of the device. 

b_private is a private field for use by the driver. The system does not interpret 
it. The driver is free to use it in whatever manner it chooses. For example, the 
driver could use it as part of a disk block sorting algorithm. 

NOTES 

Buffers are a shared resource within the kernel. Drivers should only read or 
write the members listed in this section in accordance with the rules given above. 
Drivers that attempt to use undocumented members of the buf structure risk cor¬ 
rupting data in the kernel and on the device. 

DDI/DKI conforming drivers may only use buffer headers that have been allo¬ 
cated using geteblk, ngeteblk or getrbuf, or have been passed to the driver 
strategy routine. 

SEE ALSO 

strategy(D2DK), biodone(D3DK), bioerror(D3DK), biowait(D3DK), 
brelse(D3DK), clrbuf(D3DK), freerbuf(D3DK), geteblk(D3DK), 
get error (D3DK), getrbuf (D3DK), ngeteblk(D3DK), physiock(D3DK), 
iovec(D4DK), uio(D4DK) 
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SEE ALSO 

Programmer's Guide: STREAMS 

datab(D4DK), msgb(D4DK), copyresp(D4DK), iocblk(D4DK), messages(D5DK) 
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NAME 

datab - STREAMS data block structure 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/streain.h> 

DESCRIPTION 

The datab structure describes the data of a STREAMS message. The actual data 
contained in a STREAMS message is stored in a data buffer pointed to by this 
structure. A message block structure [msgb(D4DK)] includes a field that points to 
a datab structure. 

A data block can have more than one message block pointing to it at one time, so 
the db_ref member keeps track of a data block's references, preventing it from 
being deallocated until all message blocks are finished with it. 

STRUCTURE MEMBERS 

uchar_t *db_base; /* first byte of buffer */ 
uchar_t *db_lim; /* last byte (+1) of buffer */ 

uchar_t db_ref; /* # of message pointers to this data */ 

uchar_t db_type; /* message type */ 

The db_base field points to the beginning of the data buffer. Drivers and 
modules should not change this field. 

The db_lim field points to one byte past the end of the data buffer. Drivers and 
modules should not change this field. 

The db_ref field contains a count of the number of message blocks sharing the 
data buffer. If it is greater than 1, drivers and modules should not change the 
contents of the data buffer. Drivers and modules should not change this field. 

The db_type field contains the message type associated with the data buffer. 
This field can be changed by the driver. However, if the db_ref field is greater 
than 1, this field should not be changed. 

NOTES 

The datab structure is defined as type dblk_t. 

SEE ALSO 

Programmer's Guide: STREAMS 

f ree_rtn(D4DK), msgb(D4DK), messages(D5DK) 
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NAME 

iocblk - STREAMS ioctl structure 

SYNOPSIS 

#include <sys/stream.h> 

DESCRIPTION 

The iocblk structure describes a user's ioctl(2) request. It is used in M_I0CTL, 
M_I0CACK, and M_IOCNAK messages. Modules and drivers usually convert 
M_I0CTL messages into M_I0CACK or M_IOCNAK messages by changing the type 
and updating the relevant fields in the iocblk structure. When processing a 
transparent ioctl, the iocblk structure is usually overlaid with a 
copyreq(D4DK) structure. The stream head guarantees that the message is large 
enough to contain either structure. 

STRUCTURE MEMBERS 


int 


ioc_cand; 

/* 

ioctl command */ 

cred_ 

_t 

*ioc_cr; 

/* 

user credentials */ 

uint_ 

_t 

ioc_id; 

/* 

ioctl ID */ 

uint_ 

_t 

ioc_count; 

/* 

number of bytes of data */ 

int 


ioc_error; 

/* 

error code for M_IOCACK or M_IOCNAK */ 

int 


ioc_rval; 

/* 

return value for M_IOCACK */ 


The ioc_cind field is the ioctl command request specified by the user. 

The ioc_cr field contains a pointer to the user credentials. 

The ioc_id field is the ioctl ID, used to uniquely identify the ioctl request in 
the stream. 

The ioc_count field specifies the amount of user data contained in the M_lOCTL 
message. User data will appear in M_DATA message blocks linked to the M_lOCTL 
message block. If ioc_count is set to the special value TRANSPARENT, then the 
ioctl request is "transparent." This means that the user did not use the l_STR 
format of STREAMS ioctls and the module or driver will have to obtain any 
user data with M_C0PYIN messages, and change any user data with M_C0Py0UT 
messages. In this case, the M_DATA message block linked to the M_IOCTL message 
block contains the value of the arg parameter in the ioctl system call. For an 
M_I0CACK message, the ioc_coxmt field specifies the amount of data to copy 
back to the user's buffer. 

The ioc_error field can be used to set an error for either an M_IOCACK or an 
M_I0CNAK message. 

The ioc_rval field can be used to set the return value in an M_IOCACK message. 
This will be returned to the user as the return value for the ioctl system call 
that generated the request. 

NOTES 

Data cannot be copied to the user's buffer with an M_I0CACK message if the 
ioctl is transparent. 
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NAME 

iovec - data storage structure for I/O using uio(D4DK) 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/uio.h> 

DESCRIPTION 

An iovec structure describes a data storage area for transfer in a uio structure. 
Conceptually, it may be thought of as a base address and length specification. 

STRUCTURE MEMBERS 

caddr_t iov_base; /* base address of the data storage area */ 
int iov_len; /* size of the data storage area in bytes */ 

The driver may only set iovec structure members to initialize them for a data 
transfer for which the driver created the iovec structure. The driver must not 
otherwise change iovec structure members. However, drivers may read them. 
The iovec structure members available to the driver are: 

iov_base contains the address for a range of memory to or from which data are 
transferred. 

iov_len contains the number of bytes of data to be transferred to or from the 
range of memory starting at iov_base. 

NOTES 

A separate interface does not currently exist for allocating iovec(D4DK) struc¬ 
tures when the driver needs to create them itself. Therefore, the driver may 
either use kmem_zalloc(D3DK) to allocate them, or allocate them statically. 

SEE ALSO 

physiock(D3DK), uiomove(D3DK), ureadc(D3DK), uvy7ritec(D3DK), uio(D4DK) 
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NAME 

module_info - STREAMS driver and module information structure 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/conf.h> 
ttinclude <sys/stream.h> 

DESCRIPTION 

When a module or driver is declared, several identification and limit values can 
be set. These values are stored in the inodule_info structure. These values are 
used to initialize the module's or driver's queues when they are created. 

After the initial declaration, the modulejnfo structure is intended to be read¬ 
only. However, the flow control limits (mi_hiwat and mi_lowat) and the packet 
size limits (mi_minpsz and mi_maxpsz) are copied to the queue(D4DK) structure, 
where they may be modified. 

STRUCTURE MEMBERS 


ushort_t 

mijdnum; 

/* 

module ID number */ 


char 

*mijdname; 

/* 

module name */ 


long 

mi_niinpsz; 

/* 

minimum packet size 

*/ 

long 

mi_ina3q)sz; 

/* 

maximum packet size 

*/ 

ulong_t 

mi_hiwat; 

/* 

high water mark */ 


ulong_t 

nd. Jowat; 

/* 

low water mark */ 



The mijdnum field is a unique identifier for the driver or module that distin¬ 
guishes the driver or module from the other drivers and modules in the system. 

The mijdname field points to the driver or module name. The constant 
FMNAMESZ limits the length of the name, not including the terminating NULL. It is 
currently set to eight characters. 

The mi_minpsz field is the default minimum packet size for the driver or module 
queues. This is an advisory limit specifying the smallest message that can be 
accepted by the driver or module. 

The mi_inaxpsz field is the default maximum packet size for the driver or module 
queues. This is an advisory limit specifying the largest message that can be 
accepted by the driver or module. 

The mi_hiwat field is the default high water mark for the driver or module 
queues. This specifies the number of bytes of data contained in messages on the 
queue such that the queue is considered full and hence flow-controlled. 

The mi_lowat field is the default low water mark for the driver or module 
queues. This specifies the number of bytes of data contained in messages on the 
queue such that the queue is no longer flow-controlled. 

NOTES 

There may be one modulejnfo structure per read and write queue, or the driver 
or module may use the same modulejnfo structure for both the read and write 
queues. 
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NAME 

msgb - STREAMS message block structure 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/streain.h> 

DESCRIPTION 

A STREAMS message is made up of one or more message blocks, referenced by a 
pointer to a msgb structure. When a message is on a queue, all fields are read¬ 
only to drivers and modules. 

STRUCTURE MEMBERS 


struct msgb 

*b_next; 

/* 

next message on queue */ 

struct msgb 

*b_prev; 

/* 

previous message on queue */ 

struct msgb 

*b_cont; 

/* 

next block in message */ 

uchar_t 

*b_rptr; 

/* 

1st unread data byte of buffer */ 

uchar_t 

*b_wptr; 

/* 

1st unwritten data byte of buffer */ 

struct datab 

*b_datap; 

/* 

pointer to data block */ 

uchar_t 

b_band; 

/* 

message priority */ 

ushort_t 

b_flag; 

/* 

used by stream head */ 


The b_next and h_j>rev pointers are used to link messages together on a 
queue(D4DK). These fields can be used by drivers and modules to create linked 
lists of messages. 

The b_cont pointer links message blocks together when a message is composed 
of more than one block. Drivers and modules can use this field to create complex 
messages from single message blocks. 

The b_rptr and b_wptr pointers describe the valid data region in the associated 
data buffer. The b_rptr field points to the first unread byte in the buffer and the 
b_wptr field points to the next byte to be written in the buffer. 

The b_datap field points to the data block [see datab(D4DK)] associated with the 
message block. This field should never be changed by modules or drivers. 

The b_band field contains the priority band associated with the message. Normal 
priority messages and high priority messages have b_band set to zero. High 
priority messages are high priority by virtue of their message type. This field can 
be used to alter the queueing priority of the message. The higher the priority 
band, the closer to the head of the queue the message is placed. 

The b_f lag field contains a bitmask of flags that can be set to alter the way the 
stream head will process the message. Valid flags are: 

MSGMARK The last byte in the message is '"marked." This condition is 
testable from user level via the I_ATMARK ioctl(2). 

NOTES 

The msgb structure is defined as type mblk_t. 

SEE ALSO 

Programmer's Guide: STREAMS 

allocb(D3DK), esballoc(D3DK), freeb(D3DK), datab(D4DK), 
free_rtn(D4DK), messages(D5DK) 
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NAME 

queue - STREAMS queue structure 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/streain.h> 

DESCRIPTION 

A instance of a STREAMS driver or module consists of two queue structures, one 
for upstream (read-side) processing and one for downstream (write-side) process¬ 
ing. This structure is the major building block of a stream. It contains pointers 
to the processing procedures, pointers to the next queue in the stream, flow con¬ 
trol parameters, and a list of messages to be processed. 

STRUCTURE MEMBERS 


struct qinit 

*q_qinfo; 

/* 

module or driver entry points */ 


struct msgb 

*q_first; 

/* 

first message in queue */ 


struct msgb 

*q_last; 

/* 

last message in queue */ 


struct queue 

*q_next; 

/* 

next queue in stream */ 


void 

*a ptr; 

/* 

pointer to private data structure 

*/ 

ulong_t 

q_count; 

/* 

approximate size of message queue 

*/ 

ulong_t 

q_flag; 

/* 

status of queue */ 


long 

q_minpsz; 

/* 

smallest packet accepted by QUEUE 

*/ 

long 

q_maxpsz; 

/* 

largest packet accepted by QUEUE * 

7 

ulong_t 

q_hiwat; 

/* 

high water mark */ 


ulong_t 

q_lowat; 

/* 

low water mark */ 



The q_qinfo field contains a pointer to the qinit(D4DK) structure specifying the 
processing routines and default values for the queue. This field should not be 
changed by drivers or modules. 

The q_first field points to the first message on the queue, or is NULL if the 
queue is empty. This field should not be changed by drivers or modules. 

The q_last field points to the last message on the queue, or is NULL if the queue 
is empty. This field should not be changed by drivers or modules. 

The q_next field points to the next queue in the stream. This field should not be 
changed by drivers or modules. 

The q_ptr field is a private field for use by drivers and modules. It provides a 
way to associate the driver's per-minor data structure with the queue. 

The q_count field contains the number of bytes in messages on the queue in 
priority band 0. This includes normal messages and high priority messages. 

The q_f lag field contains a bitmask of flags that indicate different queue charac¬ 
teristics. No flags may be set or cleared by drivers or modules. However, the 
following flags may be tested: 

QREADR The queue is the read queue. Absence of this flag implies a write 

queue. 
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NAME 

streamtab - STREAMS driver and module declaration structure 


SYNOPSIS 

#include <sys/stream.h> 


DESCRIPTION 

Each STREAMS driver or module must have a streamtab structure. The stream- 
tab structure must be named prefixinfo, where prefix is the driver prefix. 

The streamtab structure is made up of pointers to qinit structures for both the 
read and write queue portions of each module or driver. (Multiplexing drivers 
require both upper and lower qinit structures.) The qinit structure contains 
the entry points through which the module or driver routines are called. 


STRUCTURE MEMBERS 

struct qinit *st_rdinit; 
struct qinit *st_wrinit; 
struct qinit *st_inuxrinit; 
struct qinit *st_muxv7init; 


/* read queue */ 

/* write queue */ 

/* lower read queue*/ 
/* lower write queue*/ 


The st_rdinit field contains a pointer to the read-side qinit structure. For a 
multiplexing driver, this is the qinit structure for the upper read side. 

The st_wrinit field contains a pointer to the write-side qinit structure. For a 
multiplexing driver, this is the qinit structure for the upper write side. 

The st_muxrinit field contains a pointer to the lower read-side qinit structure 
for multiplexing drivers. For modules and non-multiplexing drivers, this field 
should be set to NULL. 

The st_muxwinit field contains a pointer to the lower write-side qinit structure 
for multiplexing drivers. For modules and non-multiplexing drivers, this field 
should be set to NULL. 

SEE ALSO 

qinit(D4DK) 
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stroptions(D4DK) 


DDI/DKI(STREAMS) 


stroptions(D4DK) 


SO_TOSTOP Stop processes on background writes to this stream. 

SO_TONSTOP Don't stop processes on background writes to this stream. 

SO_BAND The water marks changes affect the priority band specified by 

the so_band field. 

The so_readopt field specifies options for the stream head that alter the way it 
handles read(2) calls. This field is a bitmask whose flags are grouped in sets. 
Within a set, the flags are miitually exclusive. The first set of flags determines 
how data messages are treated when they are read: 

RNORM Normal (byte stream) mode, read returns the lesser of the 

number of bytes asked for and the number of bytes available. 
Messages with partially read data are placed back on the head 
of the stream head read queue. This is the default behavior. 

RMSGD Message discard mode, read returns the lesser of the number 

of bytes asked for and the number of bytes in the first message 
on the stream head read queue. Messages with partially read 
data are freed. 

RMSGN Message non-discard mode, read returns the lesser of the 

number of bytes asked for and the number of bytes in the first 
message on the stream head read queue. Messages with par¬ 
tially read data are placed back on the head of the stream head 
read queue. 

The second set of flags determines how protocol messages (M_PROTO and 
M_PCPROTO) are treated during a read: 

RPROTNORM Normal mode, read fails with the error code EBADMSG if there 
is a protocol message at the front of the stream head read 
queue. This is the default behavior. 

RPROTDIS Protocol discard mode, read discards the M_PROTO or 

M_PCPROTO portions of the message and return any M_DATA por¬ 
tions that may be present. M_PASSFP messages are also freed in 
this mode. 

RPROTDAT Protocol data mode, read treats the M_PROTO or m:_PCPROTO 

portions of the message as if they were normal data (that is, 
they are delivered to the user.) 

The so_wroff field specifies a byte offset to be included in the first message 
block of every M_DATA message created by a write(2) and the first M_DATA mes¬ 
sage block created by each call to putmsg(2). 

The so_minpsz field specifies the minimum packet size for the stream head read 
queue. 

The so_inaxpsz field specifies the maximum packet size for the stream head read 
queue. 

The so_hiwat field specifies the high water mark for the stream head read queue. 
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uio(D4DK) 


DDI/DKI 


uio(D4DK) 


NAME 

uio - scatter/gather I/O request structure 

SYNOPSIS 

ttinclude <sys/types.h> 

#include <sys/file.h> 

#include <sys/uio.h> 

DESCRIPTION 

The uio structure describes an I/O request that can be broken up into different 
data storage areas (scatter/gather I/O). A request is a list of iovec(D4DK) struc¬ 
tures (base/length pairs) indicating where in user space or kernel space the data 
are to be read/written. 

The contents of the uio structure passed to the driver through the entry points in 
section D2 should not be changed directly by the driver. The uioinove(D3DK), 
ureadc(D3DK), and uwritec(D3DK) functions take care of maintaining the the 
uio structure. A block driver may also use the physiock(D3DK) function to per¬ 
form unbuffered I/O. physiock also takes care of maintaining the uio structure. 

A driver that creates its own uio structures for a data transfer is responsible for 
zeroing it prior to initializing members accessible to the driver. The driver must 
not change the uio structure afterwards; the functions take care of maintaining 
the uio structure. 

STRUCTURE MEMBERS 


iovec_t 

*uio_iov; 

/* 

Pointer to the start of the 

iovec */ 



/* 

array for the uio structure 

*/ 

int 

uio_iovcnt; 

/* 

The number of iovecs in the 

array */ 

off_t 

uio_offset; 

/* 

offset into file where data 

are */ 



/* 

transferred from or to */ 


short 

uio_segflg; 

/* 

Identifies the type of I/O transfer */ 

short 

uio_finode; 

/* 

File mode flags */ 


int 

uio_resid; 

/* 

Residual count */ 



The driver may only set uio structure members to initialize them for a data 
transfer for which the driver created the uio structure. The driver must not oth¬ 
erwise change uio structure members. However, drivers may read them. The 
uio structure members available for the driver to test or set are described below: 

uio_iov contains a pointer to the iovec array for the uio structure. If the driver 
creates a uio structure for a data transfer, an associated iovec array must also be 
created by the driver. 

uio_iovcnt contains the number of elements in the iovec array for the uio 
structure. 

uio_offset contains the starting logical byte address on the device where the 
data transfer is to occur. Applicability of this field to the the driver is device¬ 
dependent. It applies to randomly accessed devices, but may not apply to all 
sequentially accessed devices. 
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dma_buf{D4X) 


DDI 


dma_buf(D4X) 


NAME 

caina_buf - DMA buffer descriptor structure 

SYNOPSIS 

#include <sys/types.h> 
ttinclude <sys/dina.h> 

DESCRIPTION 

The DMA buffer descriptor structure is used to specify the data to be transferred 
by a DMA operation. Each DMA operation is controlled by a DMA command 
block [see dma_cb(D4X)] structure that includes pointers to two dina_buf struc¬ 
tures. 


Each dina_buf structure provides the physical address and size of a data block 
involved in a DMA transfer. Scatter/gather operations involving multiple data 
blocks may be implemented by linking together multiple dina_bufs in a singly- 
linked list. Each dina_buf includes both the virtual and physical address of the 
next DMA buffer descriptor in the list. 

DMA buffer descriptor structures should only be allocated via 
dma_get_buf(D3X). Although drivers may access the members listed below, they 
should not make any assumptions about the size of the structure or the contents 
of other fields in the structure. 


STRUCTURE MEMBERS 


ushort_t 
paddr_t 
paddr_t 
struct ditia_buf 
ushort_t 


count; 
address; 
physical; 
*next_buf; 
count_hi; 


/* size of block*/ 

/* physical address of data block */ 

/* physical address of next dina_buf */ 
/* next buffer descriptor */ 

/* for big blocks */ 


The members of the dina_buf structure are: 

count specifies the low-order 16 bits of the size of the data block in bytes, 
address specifies the physical address of the data block. 

physical specifies the physical address of the next dma_buf in a linked list of 
DMA buffers descriptors. It should be NULL if the buffer descriptor is the last 
one in the list. Note that a DMA buffer descriptor allocated by dma get buf will 
be zeroed out initially, thus no explicit initialization is required for this field if a 
value of NULL is desired. 

next_buf specifies the virtual address of the next dina_buf in a linked list of 
DMA buffer descriptors. It should be NULL if the buffer descriptor is the last one 
in the list. Note that a DMA buffer descriptor allocated by dm a g et buf will be 
zeroed out initially, thus no explicit initialization is required for this field if a 
value of NULL is desired. 

count_hi specifies the high-order 16 bits of the size of the data block in bytes. 
Since a dma_buf allocated by dma_get_buf is initially zeroed out, no explicit ini¬ 
tialization is required for this field if the size of the data block may be specified 
by a ushort_t. 
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dma cb(D4X) 


DDI 


dma cb(D4X) 


NAME 

dina_cb - DMA command block structure 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/dina.h> 

DESCRIPTION 

The DMA command block structure is used to control a DMA operation. Each 
DMA operation requested by a driver is controlled by a command block structure 
whose fields specify the operation to occur. 

A number of fields of the DMA control block come in pairs: one for the requestor 
and one for the target. The requestor is the hardware device that is requesting 
the DMA operation, while the target is the target of the operation. The typical 
case is one in which the requestor is an I/O device and the target is memory. 

DMA command block structures should only be allocated via dma g et cb(D3X). 
Although drivers may access the structure members listed below, they should not 
make any assumptions about the size of the structure or the contents of other 
fields in the structure. 

STRUCTURE MEMBERS 


struct c3ina_buf 

*targbufs; 

/* 

list of target data buffers */ 

struct dina_buf 

♦reqrbufs; 

/* 

list of requestor data buffers */ 

uchar_t 

cammaiid; 

/* 

Read/Write/Translate/Verify */ 

uchar_t 

targ_type; 

/* 

Memory/10 */ 

uchar_t 

reqr_type; 

/* 

Memory/10 */ 

uchar_t 

targ_step; 

/* 

Inc/Dec/Hold */ 

uchar_t 

reqr_step; 

/* 

Inc/Dec/Hold */ 

uchar_t 

trans_type; 

/* 

Single/Demand/Block/Cascade */ 

uchar_t 

targ_path; 

/* 

8/16/32 */ 

uchar_t 

reqr_path; 

/* 

8/16/32 */ 

uchar_t 

cycles; 

/* 

1 or 2 */ 

uchar_t 

bufprocess; 

/* 

Single/diain/Auto-Init */ 

char 

♦procparam; 

/* 

parameter buffer for appl call */ 

int 

(*proc) 0 ; 

/* 

address of application call routines */ 


The members of the dma_cb structure are: 

targbufs is a pointer to a list of DMA buffer structures [see dma_buf(D4X)] that 
describes the target of the DMA operation. 

reqrbufs is a pointer to a list of DMA buffer structures [see dma_buf (D4X)] that 
describes the requestor of the DMA operation. 

command specifies the command for the DMA operation. It may be one of the fol¬ 
lowing: 

DMA_CMD_READ Specifies a DMA read from the target to the requestor. 

DMA_CMD_WRITE Specifies a DMA write from the requestor to the target. 


3/91 


Page 1 



dma cb(D4X) 


DDI 


dma cb(D4X) 


SEE ALSO 

dina_free_cb(D3X), dina_get_best_inode(D3X), dm a g et cb(D3X), 
dma_prog(D3X), dma_swsetup(D3X), dina_swstart(D3X), dma_buf(D4X) 
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ermos(D5DK) 


DDI/DKI 


errnos(D5DK) 


NAME 

ermos - error numbers 

SYNOPSIS 

ttinclude <sys/ermo.h> 

DESCRIPTION 

The following is a list of the error codes that drivers may return from their entry 

points, or include in STREAMS messages (for example, M_ERROR messages). 

EACCES Permission denied. An attempt was made to access a file in a 

way forbidden by its file access permissions. 

EADDRINUSE The address requested is already in use. 

EADDRNOTAVAIL The address requested cannot be assigned. 

EAFNOSUPPORT The address family specified is not installed or supported on 
the host. 

EAGAIN Temporary resource allocation failure; try again later. Drivers 

can return this error when resource allocation fails, for exam¬ 
ple, kinem_alloc(D3DK) or allocb(D3DK). 

EALREADY The Operation requested is already being performed. 

EBUSY Device is busy. This can be used for devices that require 

exclusive access. 

ECONNABORTED A received connect request was aborted when the peer closed 
its endpoint. 

ECONNREFUSED The connection was refused. 

ECONNRESET The connection was reset by the peer entity. 

EDESTADDRREQ The requested operation required a destination address but 

none was supplied. 

EFAULT Bad address. Drivers should return this error whenever a call 

to copyin(D3DK) or copyout(D3DK) fails. 

EHOSTDOWN Host is down. 

EHOSTUNREACH No route to host. 

EINPRCX3RESS The operation requested is now in progress. 

EINTR Interrupted operation. Drivers can return this error whenever 

an interruptible operation is interrupted by receipt of an asyn¬ 
chronous signal. 

EINVAL Invalid argument. Drivers can return this error for operations 

that have invalid parameters specified. 

EIO An I/O error has occurred. Drivers can return this error 

when an input or output request has failed. 

EISCONN The endpoint is already connected. 
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messages (D5DK) 


DDI/DKI 


messages (D5DK) 


NAME 

messages - STREAMS messages 

SYNOPSIS 

#include <sys/stream.h> 


DESCRIPTION 

The following is a list of the STREAMS messages types that can be used by 
drivers and modules. 

M_DATA Data message. 

M_PROTO Protocol control message. 

M_BREAK Control message used to generate a line break. 

M_SIG Control message used to send a signal to processes. 

M_DEliAY Control message used to generate a real-time delay. 

M_CTL Control message used between neighboring modules and 

drivers. 


M_IOCTL 

M_SETOPTS 

M_IOCACK 

M_IOCNAK 

M_PCPROTO 

M_PCSIG 

M_READ 

M_FLUSH 

M_STOP 

M_START 

M_HANGUP 

M_ERROR 

M_COPYIN 


Control message used to indicate a user ioctl(2) request. 
Control message used to set stream head options. 

High priority control message used to indicate success of an 
ioctl request. 

High priority control message used to indicate failure of an 
ioctl request. 

High priority protocol control message. 

High priority control message used to send a signal to 
processes. 

High priority control message used to indicate the occurrence of 
a read(2) when there are no data on the stream head read 
queue. 

High priority control message used to indicate that queues 
should be flushed. 

High priority control message used to indicate that output 
should be stopped immediately. 

High priority control message used to indicate that output can 
be restarted. 

High priority control message used to indicate that the device 
has been disconnected. 

High priority control message used to indicate that the stream 
has incurred a fatal error. 

High priority control message used during transparent ioctl 
processing to copy data from the user to a STREAMS message. 
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signals (D5DK) 


DDI/DKI 


signals (D5DK) 


NAME 

signals - signal numbers 

SYNOPSIS 

#include <sys/signal.h> 

DESCRIPTION 

There are two ways to send a signal to a process. The first, proc_signal(D3DK), 
can be used by non-STREAMS drivers. The second, by using an M_SIG or 
M_PCSIG message, can be used by STREAMS drivers and modules. The following 
is a list of the signals that drivers may send to processes. 

SIGHUP The device has been disconnected. 

SIGINT The interrupt character has been received. 

SIGQUIT The quit character has been received. 

SIGWINCH The window size has changed. 

SIGURG Urgent data are available. 

SIGPOLL A pollable event has occurred. 

SIGTSTP Interactive stop of the process. 

NOTES 

The signal SIGTSTP cannot be generated with proc_signal. It is only valid 
when generated from a stream. 

SEE ALSO 

proc_ref (D3DK), proc_signal(D3DK), proc_unref (D3DK) 
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Appendix A: Migration from Release 3.2 to Release 4 Multi-Processor 


■ Replaced. The BCI routine has been removed from the DDI/DKI. The 
DDI/DKI provides a new interface that provides a similar function. 

■ Obsolete interface. The BCI routine has been removed from the 
DDI/DKI. The DDI/DKI does not provide a new interface; the interface 
itself is obsolete. For instance, the DDI/DKI does not support clist-based 
drivers; thus any routines dealing with clists have been removed from the 
DDI/DKI. 


Again, please note that this table is a guide for programmers attempting to con- 


vert old driver 

source from BCI to DDI/DKI. 


Table A-1; 3.2 to Release 4 Multi-Processor Migration 




Release 4 

BCI 

Comments 

Multi-Processor 



DDI/DKI 

adjmsg 

No change 

adjmsg 

allocb 

No change; for memory-mapped I/O, use 
esballoc 

allocb 

backq 

Obsolete interface. 

— 

bcopy 

No change 

bcopy 

brelse 

No change 

brelse 

btoc 

Replaced 

btop, btopr 

bufcall 

No change; don't use with esballoc 

bufcall 

bzero 

Word alignment no longer required 

bzero 

canon 

Obsolete interface. 

— 

canput 

New restrictions; use canputnext (q) instead 
of canput (q“>q_next); stream cannot be 
frozen; use bcanput to test specific priority 
band 

canput 

clrbuf 

No change 

clrbuf 

cmn_err 

New restrictions; cannot hold locks if level is 

cmn_err 


CE_PANIC 


copyb 

No change 

copyb 

copyin 

New restrictions; cannot hold basic locks or 

copyin or 


read/write locks 

uiomove 

copymsg 

No change 

copymsg 
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Appendix A: Migration from Release 3.2 to Release 4 Multi-Processor 


Table A-1: 3.2 to Release 4 Multi-Processor Migration (continued) 


BCI 

Comments 

Release 4 
Multi-Processor 
DDI/DKI 

getq 

read/write locks; use ngeteblk or getrbuf for 
alternate buffer sizes 

New restrictions; stream cannot be frozen 

getq 

inb 

No change 

inb 

ind 

Renamed only 

ini 

insq 

New restrictions; stream must be frozen 

insq 

inw 

No change 

inw 

iodone 

Renamed only 

biodone 

iomove 

Replaced 

uiomove 

iowait 

Renamed and new restrictions; cannot hold 

biowait 

kseg 

basic locks or read/write locks 

Obsolete interface. 

kmem_alloc 

linkb 

No change 

linkb 

longjmp 

Obsolete interface. 

— 

major 

Renamed; macro reimplemented as function 

getmajor 

makedev 

Renamed; macro reimplemented as function 

makedevice 

malloc 

Renamed only 

rmalloc 

mapinit 

Replaced 

rmallocmap 

mapwant 

Replaced 

nnalloc_wait 

max 

No change 

max 

mfree 

Renamed only 

rmfree 

min 

No change 

min 

minor 

Renamed; macro reimplemented as function 

getminor 

msgdsize 

No change 

msgdsize 

noenable 

Macro reimplemented as function and new res¬ 

noenable 

OTHERQ 

trictions; stream cannot be frozen 

Macro reimplemented as function 

OTHERQ 

outb 

No change 

outb 

outd 

Renamed only 

outl 

outw 

No change 

outw 

physck 

Replaced; functionality included in physlock 

physiock 
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Appendix A: Migration from Release 3.2 to Release 4 Multi-Processor 


Table A-1: 3.2 to Release 4 Multi-Processor Migration (continued) 


BCI 

Comments 

Release 4 
Multi-Processor 
DDI/DKI 

rmvb 

No change 

rmvb 

rmvq 

New restrictions; stream must be frozen 

rmvq 

signal 

Obsolete interface. 

— 

sleep 

Replaced 

SV_WAIT_SIG 

spl 

Replaced; splO, spll, spl4, spl5, spl6^ 
spl7 functions eliminated; splbase^ 
spltimeout/ spldisk added 

spl 

splx 

No change 

splx 

sptalloc 

Obsolete interface. 

kmem_alloc or 
physmap 

sptfree 

Obsolete interface. 

kmem_free 

strlog 

No change 

strlog 

subyte 

Replaced 

copyout, 
uiomove, or 
ureadc 

suser 

Replaced 

drv_priv 

suword 

Replaced 

copyout, 
uiomove, or 
ureadc 

testb 

Obsolete interface. 

— 

timeout 

Replaced 

itimeout 

ttclose 

Obsolete interface. 

— 

ttin 

Obsolete interface. 

— 

ttinit 

Obsolete interface. 

— 

ttiocom 

Obsolete interface. 

— 

ttioctl 

Obsolete interface. 

— 

ttopen 

Obsolete interface. 

— 

ttout 

Obsolete interface. 

— 

ttread 

Obsolete interface. 

— 

ttrstrt 

Obsolete interface. 

— 

tttimeo 

Obsolete interface. 

— 
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Appendix B: Migration from Release 4 to Release 4 Multi-Processor 


convert old driver source from Release 4 to Release 4 Multi-Processor. All rou¬ 
tines in the Release 4 DDI/DKI, regardless of their status in the Release 4 
Multi-Processor DDI/DKI, are provided in System V Release 4 Multi-Processor 
for Intel Processors for compatibility. 


Table B-1: Release 4 to Release 4 Multi-Processor Migration 


Release 4 
DDI/DKI 

Comments 

Release 4 
Multi-Processor 
DDI/DKI 

bcanput 

New restrictions; use bcanputnext (q, 
pri) instead of bcanput (q->q_next, 
pri); stream cannot be frozen 

bcanput 

biowait 

New restrictions; cannot hold basic locks or 
read/write locks 

biowait 

bp_inapin 

New restrictions; cannot hold basic locks or 
read/write locks 

bp_inapin 

canput 

New restrictions; use canputnext (q) 
instead of canput (q->q_next); stream 
cannot be frozen 

canput 

chpoll 

New restrictions; size of pollhead struc¬ 
ture is not guaranteed; may not call any 
function that sleeps 

chpoll 

caiin_err 

New restrictions; cannot hold locks if level 
is CE_PANIC 

cinn_err 

copyin 

New restrictions; cannot hold basic locks or 
read/write locks 

copyin 

copyout 

New restrictions; cannot hold basic locks or 
read/write locks 

copyout 

delay 

New restrictions; cannot hold basic locks or 
read/write locks 

delay 

<3ina__pageio 

New restrictions; cannot hold basic locks or 
read/write locks 

dina_pageio 

enableok 

New restrictions; stream cannot be frozen 

enableok 

flushband 

New restrictions; stream cannot be frozen 

flushband 

flushq 

New restrictions; stream cannot be frozen 

flushq 
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Appendix B: Migration from Release 4 to Release 4 Multi-Processor 


Table B-1: Release 4 to Release 4 Multi-Processor Migration (continued) 


Release 4 
DDI/DKI 

Comments 

Release 4 
Multi-Processor 
DDI/DKI 

putnext 

New restrictions; cannot hold locks; stream 
cannot be frozen 

putnext 

putq 

New restrictions; stream cannot be frozen 

putq 

qenable 

New restrictions; stream cannot be frozen 

qenable 

qreply 

New restrictions; cannot hold locks; stream 
cannot be frozen 

qreply 

qsize 

New restrictions; stream cannot be frozen 

qsize 

RD 

Extended. Accepts both read and write 
queue pointers 

RD 

rndnit 

Replaced 

rmallocmap 

nnsetwant 

Replaced 

rmalloc_wait 

rmvq 

New restrictions; stream must be frozen 

rmvq 

SAMESTR 

New restrictions; argument cannot refer¬ 
ence q_next; stream cannot be frozen 

SAMESTR 

sleep 

Replaced 

SV_WAIT_SIG 

spl 

Replaced; splO^ spll, spl4, spl5, 
spl6, spl7 functions eliminated; 
splbase, spl timeout, spldisk added 

spl 

strqget 

New restrictions; stream must be frozen 

strqget 

strqset 

New restrictions; stream must be frozen 

strqset 

timeout 

Replaced 

itimeout 

uiomove 

New restrictions; cannot hold basic locks or 
read/write locks if uio_segflg is 

UIO_USERSPACE 

uiomove 

unbufcall 

Interface changed and new restrictions; 
argument type changed from int to 
toid_t; cannot hold locks 

unbufcall 

untimeout 

Interface changed and new restrictions; 
argument type changed from int to 
toid_t; cannot hold locks 

untimeout 
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Appendix B: Migration from Reiease 4 to Reiease 4 Muiti-Processor 


Tabie B-2: Additions to the DDI/DKI in Reiease 4 Muiti-Processor (continued) 


Routine 

Section 

Description 

RW_DEALLOC 

D3DK 

deallocate an instance of a read/write lock 

rw_rdlcx:k 

D3DK 

acquire a read/write lock in read mode 

RW_TRYRDLOCK 

D3DK 

try to acquire a read/write lock in read mode 

RW_TRYWRLOCK 

D3DK 

try to acquire a read/write lock in write mode 

RW_UNLOCK 

D3DK 

release a read/write lock 

RW_WRIiOCK 

D3DK 

acquire a read/write lock in write mode 

SLEEP_ALLCX: 

D3DK 

allocate and initialize a sleep lock 

SLEEP_DEALLOC 

D3DK 

deallocate an instance of a sleep lock 

SLEEP_LOCK 

D3DK 

acquire a sleep lock 

sleep_lcx:kavail 

D3DK 

query whether a sleep lock is available 

SLEEP_LOCKOWlSIED 

D3DK 

query whether a sleep lock is held by the caller 

SLEEP_IiOCK_SIG 

D3DK 

acquire a sleep lock 

SLEEP_TRYLOCK 

D3DK 

try to acquire a sleep lock 

sleep_unlcx:k 

D3DK 

release a sleep lock 

SV_ALI.OC 

D3DK 

allocate and initialize a synchronization vari¬ 
able 

SV_BROADCAST 

D3DK 

wake up all processes sleeping on a synchroni¬ 
zation variable 

SV_DEALIiOC 

D3DK 

deallocate an instance of a synchronization 
variable 

SV_SIGNAL 

D3DK 

wake up one process sleeping on a synchroni¬ 
zation variable 

SV_WAIT 

D3DK 

sleep on a synchronization variable 

SV_WAIT_SIG 

D3DK 

sleep on a synchronization variable 

TRYLOCK 

D3DK 

try to acquire a basic lock 

UNLOCK 

D3DK 

release a basic lock 

bcanputnext 

D3DK 

test for flow control in a specified priority band 

bioerror 

D3DK 

manipulate error field within a buffer header 

canputnext 

D3DK 

test for flow control in a stream 

dtimeout 

D3DK 

execute a function on a specified processor. 
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ics find rec(DSD) DDI(Multibus II) ics find rec(DSD) 

NAME 

ics_find _rec - reads the interconnect register of the board in the specified 
slot. 

SYNOPSIS 

ttinclude <sys/ics,h> 
int ics_find_rec {slot, recordid) 
unsigned short slot; 
unsigned char recordid; 

ARGUMENTS 

slot the slot number of the board that will be searched 

recordid the record ID of the searched-for record 

DESCRIPTION 

icsjindjrec finds a specific record in the interconnect space of a board. 

RETURN VALUE 

If the searched-for record is found, its starting register number is returned. Oth¬ 
erwise, -1 is returned. 

LEVEL 

Base or Interrupt 

SEE ALSO 

ics_read(D3D), ics_write(D3D) 
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NAME 

ics_rdwr - reads or writes a specified number of interconnect space registers 
from a given cardslot ID 

SYNOPSIS 

#include <sys/ics.h> 
void ics_rdwr {cmd, addr) 
int cand; 

struct ics_rw_struct *addr; 

ARGUMENTS 

cmd Either ICS_READ_ICS or ICS_WRITE_ICS. 

addr A pointer to the description of the buffers to be used for the transfer. 

DESCRIPTION 

The ics_rdwr routine reads or writes a specified number of interconnect space 
registers from a given cardslot ID. 

In both interconnect space and in memory, addr is a pointer to the description of 
the buffers to be used for the transfer, addr contains fields for length and 
addresses. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 

SEE ALSO 

ics_read(D3D), ics_write(D3D) 
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DDI(Multibus II) 


Ics write (DSD) 


NAME 

ics_write - writes a value into the specified register of the board in the 
specified slot. 

SYNOPSIS 

#include <sys/ics.h> 
int ics_write {slot, register, value) 
unsigned short slot; 
unsigned short register; 
xmsigned char value; 

ARGUMENTS 

slot The slot id of the board. 

register The register number of the board's interconnect space record. 
value The value to be written into the specified register 

DESCRIPTION 

ics_write writes value into register number register of the board in slot number 
slot. If no board is in the designated slot, the results are undefined. 

RETURN VALUE 

If the write is successful, 0 is returned. If the register number specified does not 
exist in the interconnect space of the board, EINVAL is returned. 

LEVEL 

Base or Interrupt 

SEE ALSO 

ics_read(D3D), ics_rdwr(D3D) 
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DDI(Multibus II) 


mps AMPreceive frag (DSD) 


NAME 

mps_AMPreceive_frag - receives solicited data in fragments when buffer space 
is not available at the receiving agent 

SYNOPSIS 

ttinclude <sys/mps.h> 

long iips_AMPreceive_frag(c/zan, mbp, socid, tid, ibuf) 

long chan; 

nps_msgbuf_t *inbp; 

mb2socid_t socid; 

unsigned char tid; 

struct dina_buf *ibuf; 

ARGUMENTS 

chan Channel number received from a previous mps_open_chan. 
mbp Points to a message buffer. 

socid Identifies socket id of the socket which initiated the transaction. 
tid Identifies the transaction corresponding to this nips_AMPreceive_f rag. It 
is obtained from the request message. 

ibuf Specifies the data buffer to receive incoming data. Indication of comple¬ 
tion of transfer is sent to intr via a message. 

DESCRIPTION 

nps_AMPreceive_frag is used when an agent sending solicited data requests 
buffer space that is not available at the receiving agent. After the Buffer Reject 
message is sent, the receiving agent can use itps_AMPreceive_frag to receive the 
solicited data in fragments depending on the available buffer space in the receiv¬ 
ing agent. See the Multibus II Transport Protocol Specification and Designer's Guide 
for additional information. 

The iips_AMPreceive_frag routine queues up the message to initiate the 
transfer, sets up table entries to receive data messages, and returns immediately. 
This routine is asynchronous in operation. 

Applications must ensure that iiips_AMPreceive_frag is repeatedly used the 
correct number of times with the correct fragment buffer length to transfer an 
entire request. 

RETURN VALUE 

If no error is detected, 0 (zero) is returned. When an error is detected, -1 is 
returned. 

LEVEL 

Base or Interrupt 

SEE ALSO 

itps_open_chan(D3D) 
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mps AMPsend rsvp (DSD) 


NAME 

ittps_AMPsend_rsvp - queues request messages for transmission and sets up table 
entries for reply messages 

SYNOPSIS 

ttinclude <sys/nps.h> 

long itps_AMPsend_rsvp(c/zfln, omsg, obuf, ibuf) 

long chan; 

inps_msgbuf_t *omsg; 

struct dina_buf *obuf, *ibuf; 

ARGUMENTS 

chan Channel number received from a previous mps_open_ chan. 

omsg Points to a message buffer containing message to be sent. 

obuf Specifies a data buffer for data to be sent. 

ibuf Specifies a data buffer to receive replies. 

DESCRIPTION 

iips_AMPsend_rsvp queues up request messages for transmission and sets up 
table entries for reception of reply messages when they arrive. This routine is 
asynchronous in operation. 

When obuf is NULL, the request message is assumed to be an unsolicited mes¬ 
sage. In this case iiips_mk_unsol (with a non-zero tid obtained by a call to 
mps g et tid) should be used to build the message in omsg. When obuf is not 
NULL, request message is assumed to be a solicited message and obuf points to 
the data. In this case itips_ink_uiisol (with a non-zero tid obtained by a call to 
mps get tid) should be used to build the message in omsg. 

When obuf is not NULL, the request message is assumed to be a solicited message 
and obuf points to the solicited data. In this case, nps_mk_sol (with a non-zero 
tid obtained by a call to mps_get_tid) should be used to build the message in 
omsg. If ibuf is NULL, the reply message is expected to be an unsolicited mes¬ 
sage. 

RETURN VALUE 

itps_AMPsend_rsvp returns 0 (zero) if no error is detected; otherwise, -1 is 
returned. 

LEVEL 

Base or Interrupt 

SEE ALSO 

mps_open_chaii(D3D), mps_mk_sol(D3D), mps_mk_unsol(D3D), 
mps g et t id(D3D) 
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NAME 

inps_AMPsend_reply - replies to a received request that is part of a request- 
response transaction 

SYNOPSIS 

ttinclude <sys/mps.h> 

long itps_AMPsend_reply(c/ian, omsg, obuf) 
long chan; 
itps_msgbuf_t *amsg; 
struct dma_buf *obuf; 

ARGUMENTS 

chan 
omsg 


obuf 


DESCRIPTION 

nps_AMPsend__reply is used to send a reply in response to a received request 
that is part of a request-response transaction. The nps_AMPsend_reply routine is 
asynchronous in operation. nips_AMPsend_reply returns immediately, queuing 
up to send the reply. Be sure to use the tid from the corresponding received 
request. 

nips_AMPsend_reply can be used to send a reply as a number of solicited frag¬ 
ments. The message buffer in the last reply fragment should have the EOT flag 
set to 1. 

RETURN VALUE 

If no error is detected, 0 (zero) is returned; otherwise -1 is returned. 

LEVEL 

Base or Interrupt 

SEE ALSO 

irps_mk_solrply(D3D), mps_ink_unsolrply(D3D), nips_open_chan(D3D) 


Channel number received from a previous inps_open_chan. 

Points to a message buffer containing the message to be sent. The 
message in omsg should be constructed using nips_ink_solrply or 
mps_ink_unsolrply (depending on whether obuf is NULL or not) 
with the EOT flag set appropriately. 

Points to a data buffer containing data to be sent. When obuf is 
NULL, the reply message is assumed to be an unsolicited message. 
When obuf is not NULL, the reply message is assumed to be a soli¬ 
cited message. A completion indication is sent via a message to the 
appropriate intr routine. 
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mps close chan (DSD) 


NAME 

nips_close_chan - closes a previously opened channel 

SYNOPSIS 

#include <sys/mps.h> 
long nips_close_chan (chan) 
long chcin; 

ARGUMENTS 

chan Specifies the channel to be closed. 

DESCRIPTION 

This routine is used to close a previously opened channel. To close a channel a 
device driver must identify the channel. 

The nigps_close_chan routine is synchronous in operation. mps_close_chan fails 
if a transaction is in progress on the specified channel. 

RETURN VALUE 

When inps_close_chan succeeds it returns 0 (zero). When nps_close__chan 
fails, it returns -1 and the channel is not closed. 

LEVEL 

Base or Interrupt 

SEE ALSO 

ingps_open_chan(D3D) 
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NAME 

inps_f ree_msgbuf - puts a buffer back into the free memory pool 

SYNOPSIS 

#include <sys/mps.h> 
void inps_free_msgbuf 
raps_msgbuf_t *mbp; 

ARGUMENTS 

mbp the message buffer to be returned to the free memory pool. 

DESCRIPTION 

In this function, mbp points to a message buffer. The buffer is put back in the 
free memory pool. Note that mps_free_msgbuf accepts a pointer to a single 
message buffer, not a list of message buffers to be freed. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 

SEE ALSO 

inps_get_msgbuf (DSD) 
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mps get dmabuf (DSD) 


NAME 

nips_get_dinabuf - returns a pointer to a list of data buffer descriptors. 

SYNOPSIS 

#include <sys/iips.h> 

struct dina_buf *nps_get_dmabuf (cownf, flag) 
xmsigned int count; 
int flag; 

ARGUMENTS 

count the number of dma buffer descriptors required. 

flag determines whether the routine sleeps while waiting for resources. 

Valid values are DMA_SLEEP or DMA_NOSLEEP. 

DESCRIPTION 

The mps get dmabuf function returns a pointer to a linked list of (count number 
of) data buffer descriptors. The list is terminated by NULL in the dhjiext field of 
the data buffer. 

RETURN VALUE 

If count number of data buffer descriptors cannot be allocated, and flag = 
DMA_NOSLEEP, a NULL descriptor is returned. Otherwise, ii flag = DMA_SLEEP, the 
routine blocks until count data buffer descriptors can be allocated. 

LEVEL 

Base or Interrupt with DMA NOSLEEP 

SEE ALSO 

iips_f ree_dmabuf (DSD) 


3/91 


Page 1 



mps get reply Jen (DSD) 


DDI(Multibus II) 


mps get replyJen (DSD) 


NAME 

mps g et reply len - get data length for a solicited reply. 

SYNOPSIS 

ttinclude <sys/mps.h> 
long nips_get_reply_len(sodd, tid) 
inb2socid_t socid; 

unsigned char tid; 

ARGUMENTS 

socid The source socid for the solicited reply 

tid the transaction id of the solicited reply 

DESCRIPTION 

This function should be invoked when an rsvp completes with an unsolicited 
message, instead of with a a solicited message; ihat is, when the flags field of the 
final message buffer is MPSJVIG UNSOL. In this case, the nps_get_reply_len 
function returns the length of the data for the solicited reply associated with the 
rsvp when it is called after the transaction completes. 

RETURN VALUE 

A successful operation returns the length of the data. If an error occurs, 0 is 
returned as the data length. 

LEVEL 

Base or Interrupt 
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DDI(Multibus II) 


mps get tid(D3D) 


NAME 

nips__get_tid - allocates transaction ids. 

SYNOPSIS 

#include <sys/mps.h> 
unsigned char mps_get_tid(c/zfln) 
long chan; 

ARGUMENTS 

chan a channel number obtained from a previous call to nps_open_chan. 

DESCRIPTION 

The mps_get_tid function is used by users of the message handler to allocate 
transaction ids. 

RETURN VALUE 

If no free transaction ids are available for the associated port id, or when chan is 
an invalid channel number, 0 (zero) is returned; otherwise the allocated transac¬ 
tion id is returned. 

LEVEL 

Base or Interrupt 

SEE ALSO 

nrps_open_chan(D3D), itips_f ree_tid(D3D) 
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NAME 

ii:ps_ink_bgrant - construct a buffer grant in response to a buffer request. 

SYNOPSIS 

#include <sys/inps.h> 

void raps_ink_bgrant dsocid, lid, count) 

mps_msgbuf_t iribp; 

mb2socid_t dscocid; 

unsigned char lid; 

unsigned long count; 

ARGUMENTS 

mbp pointer to message buffer 

dsocid 32-bit destination socket id (host idiport id) 

lid liaison id 

count number of bytes to transfer 

DESCRIPTION 

The inps_mk_bgrant function is used to construct a buffer grant in response to a 
buffer request. Arguments to this function are not checked for valid values. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 

SEE ALSO 

inps_ink_unsol rply (DSD) 
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NAME 

nps_ink_breject - construct a buffer reject in response to a buffer request. 

SYNOPSIS 

#include <sys/mps.h> 
void n^s_ink_breject dsocid, lid) 

inps_msgbuf_t mbp; 

inb2socid_t dscocid; 

unsigned char lid; 

ARGUMENTS 

mbp pointer to message buffer 

dsocid 32-bit destination socket id (host idiport id) 

lid liaison id 

DESCRIPTION 

The mps_ink_breject function is used to construct a buffer reject in response to a 
buffer request. Arguments to this function are not checked for valid values. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
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NAME 

nps_ink_solrply - constructs a message to be sent to initiate a solicited data 
reply. 

SYNOPSIS 

#include <sys/mps.h> 

void mps_ink_solrply(ml7p, dsocid, tid, dptr, count, eotflag) 

mps_msgbuf_t mbp; 

mb2socid_t dscocid; 

unsigned char tid; 

unsigned char *dptr; 

unsigned long count; 

unsigned char eotflag; 

ARGUMENTS 

mbp pointer to message buffer 

dsocid 32-bit destination socket id (host idiport id) 

tid 8-bit transaction id 

dptr pointer to user data to be sent with the message 

count number of bytes of user data to be sent with the message (Max 16) 

eotflag 1 to indicate end of transaction; otherwise, 0 (zero) 

DESCRIPTION 

The mps_ink_solrply function takes a pointer to a message buffer and constructs 
a message to be sent to initiate a solicited data reply. The message is constructed 
using values supplied as arguments. Arguments to this function are not checked 
for valid values. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 

SEE ALSO 

mps_ink_unsolrply(D3D) 
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mps mk unsoirply (D3D) 


NAME 

itps_ink_unsolrply - constructs a unsolicited reply message to be sent. 


SYNOPSIS 

#include <sys/mps.h> 

void mps_ink_iinsolrply(ml7p, dsocid, tid, dptr, count) 

mps_msgbuf_t mbp; 

inb2socid_t dscocid; 

unsigned char tid; 

unsigned char *dptr; 

unsigned long count; 


ARGUMENTS 

mbp pointer to message buffer 

dsocid 32-bit destination socket id (host idrport id) 

tid 8-bit transaction id 

dptr pointer to user data to be sent with the message 

count number of bytes of user data to be sent with the message (Max 20) 

DESCRIPTION 

The nps_ink_unsolrply fimction takes a pointer to a message buffer and con¬ 
structs a unsolicited reply message to be sent. The message is constructed using 
values supplied as arguments. Arguments to this function are not checked for 
valid values. 


RETURN VALUE 

None 


LEVEL 

Base or Interrupt 

SEE ALSO 

mps_mk_sol rply (DSD) 
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mps msg(D3D) 


RETURN VALUE 

Listed above. 

LEVEL 

Base or Interrupt 
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